# Agent Discovery and Workflow Guide

AXF keeps canonical capability IDs authoritative while giving arriving agents
a bounded front door.

## Bootstrap flow

Use `guide` first when the workspace declares normal entrypoints:

```sh
axf guide
axf guide context --json
axf guide check --json
axf guide handoff --json
```

The MCP equivalent uses the same discovery implementation:

```json
{ "operation": "guide" }
```

Each recommendation exposes its canonical capability ID, lifecycle, side
effects, provenance, and an inspect invocation. `guide` never executes a
capability. Results default to 12 entries and are always bounded by a maximum
of 100.

When a workspace declares a composite session-context capability, prefer that
single operation for startup/resume/compaction. The packaged
`templates/session-context` recipe combines AXF guidance with bounded episodic
Lex history without coupling Lex into AXF core. Its optional KnowledgeFrame
provider rollout is explicit:

- `off` is the default and invokes no context provider;
- `shadow` invokes only the declared read-oriented capability and returns
  body-free provider health, selection, freshness, provenance, and budget
  telemetry;
- missing, empty, stale, invalid, or unavailable providers preserve ordinary
  guidance and continuity with structured warnings.

The composer uses one total token ledger and deterministic truncation order.
Return to `--context-mode off` for a one-line rollback. Provider indexing is a
separate write-classified capability and is never invoked by `guide` or
session start.

## Workspace recommendations

Declare repo-owned entrypoints in `axf.workspace.json`:

```json
{
  "manifestVersion": "axf/v0",
  "name": "my-repo",
  "recommendations": {
    "session-start": [
      {
        "label": "context",
        "capability": "global.my-repo.session-context"
      }
    ],
    "validation": "global.my-repo.check",
    "handoff": "global.my-repo.handoff"
  }
}
```

`context` aliases `session-start`; `check` aliases `validation`. AXF reports a
warning when a declared target is missing instead of silently substituting a
different capability.

## Family and capability recommendations

Reusable packs can recommend commands without hard-coding provider behavior in
AXF core. Put `recommendedFor` on a capability manifest or family command:

```json
{
  "commands": {
    "check": {
      "summary": "Validate the repository",
      "recommendedFor": ["validation"],
      "executionTarget": { "command": "my-cli", "args": ["check"] },
      "args": {},
      "sideEffects": "read"
    }
  }
}
```

Workspace declarations win presentation order; canonical resolution and run
policy remain unchanged.

## Compact discovery

Use compact/search discovery when the registry is larger than the immediate
workflow guide:

```sh
axf list --compact --search lex --limit 20 --json
axf list --compact --side-effects read
```

```json
{
  "operation": "list",
  "compact": true,
  "search": "lex",
  "sideEffects": "read",
  "limit": 20
}
```

Compact entries retain ID, summary, lifecycle, side effects, scope, source
kind, layer, manifest path, owner, provider, family, and mount provenance.
Full `list` output remains available when complete manifests are required.

## Agent-facing response detail

MCP responses default to `responseDetail: "compact"` because agents are the
primary AXF consumer. Compact results retain capability data, actionable
errors, warnings, and the fields needed for safe decisions while omitting
compatibility metadata and invocation traces.

Use the three named profiles deliberately:

- `compact` returns the minimum safe operation result. Failures remain
  actionable, and `inspect` still retains lifecycle, side effects, policies,
  defaults, output modes, the argument schema, and a redacted CLI launch
  summary. This is the agent-first default.
- `standard` returns the expanded canonical result without legacy aliases or
  invocation traces.
- `diagnostic` explicitly returns compatibility, provenance, workspace,
  adapter, and invocation metadata. Sensitive framework fields and values are
  redacted.

```json
{
  "operation": "run",
  "responseDetail": "compact",
  "target": { "id": "global.echo.say" },
  "args": { "message": "hello" }
}
```

Response projection applies only to AXF's envelope. Capability-owned `data`
is never truncated, summarized, redacted, or otherwise transformed. The
existing list `compact` option remains separate: it controls capability item
shape, while `responseDetail` controls the surrounding MCP result. When a
compact MCP `list` response omits `limit`, AXF independently bounds the result
to 25 entries. An explicit `limit` replaces that bound. Explicit `standard` or
`diagnostic` detail without a limit opts out and returns the complete matching
selection.

AXF 2.0 changes the implicit MCP response from the pre-2.0 rich envelope to
`compact`. Request `diagnostic` wherever a caller deliberately consumes expanded
provenance, adapter, or invocation metadata. Compact CLI inspection retains the
command, argument prefix, resolved target, working directory, and their sources;
it omits the raw execution target and environment. Framework credential
redaction applies to every profile.

All profiles retain bound `projectRoot` and `executionRoot`, even when equal.
MCP capability entries expose `registryScope` as the explicit name for AXF
registry naming/discovery scope and retain `scope` for compatibility. A value
of `global` does not identify a global storage destination or an access grant.
AXF does not derive `storageScope` from a capability ID, manifest scope, or
filesystem root. Provider destination preflights and write receipts pass through
unchanged in capability-owned `data`; callers must evaluate the provider's
verified identity and authority contract.

Project and execution roots identify filesystem bindings, not security
principals. Environment-provided roots are compatibility/configuration inputs
and are never proof of tenant, repository, workspace, grant, or authorization.
Hosts that enforce those concepts must authorize first, pass explicit roots,
and let the provider retain ownership of its identity contract. AXF neither
depends on Lex nor reconstructs Lex authority.

## Missing-capability explanations

Use `explain` rather than reconstructing registry internals:

```sh
axf explain global.lex --json
axf explain global.lex.missing-command --json
```

```json
{ "operation": "explain", "query": "global.lex.missing-command" }
```

AXF distinguishes loaded, lifecycle-filtered, prefix-only, loaded-family with
missing command, manifest-load failure, and absent capability states. Missing
results include the active project/execution roots and bounded suggestions.

## Inspect examples

`inspect` includes declared examples plus generated CLI and MCP inspect/run
shapes. Generated runs identify their shell: `run.cli` remains the canonical
PowerShell example for compatibility, `run.cliShell` names that shell, and
`run.cliByShell` provides separately escaped `powershell` and `posix` commands.
It also shows public argument names and provider flag mappings when a family
declares an `argMap`. Generated placeholders are explicit; provider- or
workspace-authored examples remain the source for real environment-specific
values.

## Manifest scan boundary

AXF reads only these AXF-owned paths:

- `manifests/capabilities/**/*.json`
- `manifests/families/*.family.json`
- `manifests/toolspaces/**/*.json`

Domain JSON elsewhere under `manifests/` is ignored. This lets repositories
keep gameplay, hook, or application manifests nearby without producing false
AXF doctor errors.