响应契约

fx <command> --help describes every flag the running executable accepts, including the global ones, and ends with an AGENT USAGE block that restates the output and error contract. This guide covers what the help cannot: how to read the results.

An unknown --workspace value never selects a different default. When a host truncates a large response, use --fields on a read-only query to retrieve the required facts. If you capture full output, keep it within the task's authorized directory: shell redirection writes a file even when the fx command is read-only.

Workflow report views

The four workflow reports (init, sync, doctor, release check) default to compact JSON. output_mode: summary and omitted describe the view; omitted counts are not pagination. All warning/failure rows and exact pending command vectors remain. --details returns the full application result; explicit --fields projects it. Explicit report projection applies in every format: JSON/NDJSON emit one object; human output emits selected key/value pairs. Dotted paths retain flat keys and array alignment. Only JSON is summarized: without explicit fields, human output keeps its own view and NDJSON carries the complete result. Fact-query projections still apply per item and retain collection metadata. Error envelopes are never projected or compacted.

For init/sync/doctor, preparation contains state (planned, ready, incomplete), next, scope, completed, blockers, warnings, unchecked, next_actions and resume. next.kind is review, complete, act or handoff. Agent next_actions exclude personal actions (actor: user) and the conditional resume; use resume only after the prerequisites change. Initialization summaries retain selected repository, guide and Skill outcomes, along with setup results, so callers can verify effects without extra discovery. The setup stage retains completed outcomes in summary mode so callers do not repeat local side effects while another step needs human input. Only required blockers prevent readiness. A blocker may carry cause (credential, permission, network) and waits_on, the blocker it waited on unchecked; resolve that one first. Actions contain actor, id, description, argv, cwd and requires_approval, with optional env coordinates for the current configuration/home and Agent selection. Preserve these values and use the returned exact executable. Credentials are never included. Init and sync also identify preview/apply through operation. Ready exits 0; incomplete preparation exits 12. Fatal failures keep their category exit codes and partial stdout. init --resume --workspace <name> uses the managed source and retains existing selection and work.

self info.bundled_skill_version identifies the instructions shipped with the running executable. skill status reports embedded_version, installation versions and activation: unverified. Installation cannot establish native host activation. Load the bundled task guide when the task needs it.

SKILL_WRITE_DENIED keeps denied filesystem paths and partial stage evidence. Check access before repeating writes. To continue local repository/guide work, use sync --only repos,docs --no-refresh-manifest in the affected workspace. This does not claim the skipped Skill stage is ready or authorize trust changes.

Shapes of the answering commands

workspace list/show resolves registry facts without requiring a valid manifest. Rows include root/source, selection and health. self info still reports global installation facts when the selected workspace is degraded. Use explicit workspace relocate, rebind or unregister plans to change identity or end management; these preserve business checkouts and respect owned-resource cleanup.

repo select / env select replace a personal collection. --all removes its explicit scope and follows future shared entries; --none stores an empty set. pick/unpick add or remove individual names. Selection output reports modes and next steps; repository selection is separate from downloading via sync.

status keeps {items, has_more} and adds workspace/root/selection context, with stray_entries naming root entries that nothing accounts for. Items preserve dirty as tracked changes and add uncommitted for tracked or untracked work. Human output includes untracked counts; --dirty filters on all uncommitted work. Empty results distinguish no declarations, no selected repos and no matching uncommitted work.

Init accepts --repos / --no-repos before cloning. Its preview distinguishes actual registration from planned effects and states whether source contents were inspected; uninspected remote contents are not a validated selection. registered means registration currently exists, including a successful retry.

Profile import merges registrations by name, retains unmentioned workspaces and refuses root/source identity changes. Its registration plan and quoted next steps identify missing manifest preparation. Use workspace lifecycle commands for relocation, rebinding and removal rather than editing an export to remove names.

fx can <capability|tool> [--env <env>] — one record:

A step's check says why it is pending. result: failed carries the detail its tool gave and, when the bundled recipe can read it, a cause: credential (authentication was not established), permission (it answered no) or network (a connection could not be completed). The step's instructions and open then already say what resolves that cause. result: blocked names in by the step it waits on; act on that one first. A missing cause means the reason is not established, which is not evidence against a sign-in: most checks declare no causes. Read detail and the step's own guidance. A missing check comes from an older fx or a check that did not run; fx doctor --tool <tool> [--env <env>] shows the tool's message.

When a tool was inspected, execution contains its canonical tool, configured binary, nullable binary_path and version, and the workspace cwd. Use this executable instead of resolving the name again in another shell. Checked provider entry/coordinate commands and direct handoff vectors use that path. Manifest shell templates stay verbatim; --no-check does not bind or verify a tool. Recheck after changing an installation. A ready tool does not establish permission for every API operation.

A bound provider without a companion tool has no installation or login check; ready means preparation is complete, not that every repository query will succeed.

When a tool has multiple viable platform bindings, can returns CAN_AMBIGUOUS rather than choosing by declaration order. Select a capability and environment, or inspect repository platforms through where.

fx can without a target — items[], one per capability a manifest binds, and per platform instance for an environment-scoped one:

The list reads bindings only and takes no --env: it says who would answer, and asking about one capability says whether they can.

fx where <repo> [--env <env>] [--platform <name>] [--no-check] [--probe] — items[], one per platform and environment:

located means the manifest resolved a coordinate, not that the repository runs there; an undeclared confidence reads derived. where checks readiness against the service unless --no-check is given, and --no-check does not turn off an explicit --probe. Pass --platform to keep one platform's check from waiting on another's. A not_covered row states what the manifest covers: its first note is the reason, and a note of the environment may follow.

fx member show <query> — items[] of people: id, display, email, status, mentor, leader, accounts (per system), matched_by, via. For author attribution, pass --system <system> and require exactly one account match. Keep ambiguous identity candidates separate. List and show return mentor and leader as explicit person IDs or null; neither is inferred from business roles, other people or date filters. Use --area <id> and optionally --scenario <id> for a business context. Keep memberships, responsible_teams, and assignments separate. Read each edge's source and status. A confirmed function without a team leaves team classification uncovered. Multiple confirmed teams are valid. candidate, multiple_candidates, not_configured, and not_covered do not confirm a team. Date filters evaluate declared intervals only. fx member list --team <id> --function <id> --area <id> requires a single matching assignment. Without business scope, either kind of relationship may match. Keep collective all separate from named people.

fx member selectors [--kind area|scenario|team|function] returns vocabulary rows with kind, canonical id, display name and nullable parent area. Results contain no people. A name supplied as an area that exactly identifies a scenario/team/function returns the corresponding explicit queries instead of an unrelated fuzzy area.

fx repo show <repo> — the resolved entry, disk state and URLs, plus owners: [] when the members document names nobody, null when the workspace has no members document at all, else items of area, lead, scenario, devLead, roles, every person as {id, name, email} (name and email null when the id is not in the document, all included); contact is the project's contact. Its next_steps use the canonical repository name and explicit workspace to select an unpicked repository and synchronize missing shared checkouts; inspection itself never changes selection or downloads files.

ownership_evidence is an additional scope-aware projection. It carries as_of, basis: current_members_document, historical_snapshot: false, coverage, items and has_more: false. Each item retains the repository-linked area/scenario, context, named people, responsibility teams and collective assignments. A person's status, mentor and leader remain explicit current facts. --as-of YYYY-MM-DD filters declared relationship intervals, defaulting to today in UTC; it does not reconstruct old membership documents. not_configured means no members document, not_covered means no linked scope, and a checked scope can still say no_relationships. Do not expand collective all or infer an assignee from Git authors. A team workflow selects an owner from applicable responsibility evidence.

fx repo version <repo> reads pinned version history for any known repository, even one excluded from the release checklist. version_evidence carries requested_ref, resolved_sha, declaration, last_change, coverage, commits_read, termination, next_sha and structured failures. declaration is {file, field, package_name, value}. last_change identifies the commit, committer time, old/new values, history_mode: first_parent and whether this is a field change or actual root declaration. A dependency edit is not a version-field change. Source path, field and package identity stay fixed during the walk; renamed files, shallow/missing parents and exhausted budgets remain incomplete. next_sha describes a stop point, not an automatic resume mechanism. The optional baseline_evidence pins both refs and compares their declarations and complete commit range. evidence_complete covers both requested facets. Use the command's help for ref, path, baseline and history-budget options.

Automatic declaration discovery skips dependency-only files such as requirements.txt. A present but unreadable supported source remains incomplete; only the documented Gradle fallback selects adjacent gradle.properties. Maven versions must be literals or one project property resolved to a literal. Composite, nested or unresolved expressions retain VERSION_DECLARATION_UNREADABLE; they are not concrete versions.

Diagnostic reports

Login and doctor reject unknown explicit tool/environment selectors before setup or repair (TOOL_UNKNOWN / ENV_NOT_FOUND). login --list reports conflicting expanded setup identities as step_conflict notices; executing that plan fails with SETUP_PLAN_CONFLICT. Inspect the provider recipes rather than retrying the same ambiguous setup. Doctor marks its missing verification as incomplete.

fx doctor returns preparation, diagnostic coverage (complete or incomplete), summary {ok, warn, fail} and findings[]. The preparation verdict owns task completion; optional host activation can remain unverified. An incomplete verdict exits 12. fx release check returns ok, complete, evidence_complete, summary and findings and exits zero when its checklist was produced. Findings carry group, id, level, coverage, message, fix and handoff; caught query errors also carry a structured failure with recovery, retained in compact JSON. Full results also carry evidence. Incomplete checks are not passes: RELEASE_INCOMPLETE means no confirmed failure but missing evidence, and a known failure can also have incomplete coverage. Human output groups identical unavailable causes separately from confirmed problems; --details expands all repository checks. A missing error-tracker project is incomplete coverage and must be corrected or explicitly marked not covered; never substitute an organization-wide query. repos[] says what each release would ship, in summaries too. For can, inspect its capability status.

Doctor groups are repos, root, tools, login, agents, manifest, self, hooks, mcp and rules. root lists entries at the workspace root that nothing accounts for; they warn without affecting preparation. manifest:docs checks derived guides; manifest:upstream checks source updates; self:version checks published CLI updates. A development build needs no update; an unavailable registry produces a warning, with a handoff when configuration is missing.

Doctor also returns repairs, empty without --fix. Summary JSON omits successful repair rows; use --details to inspect all attempts. Each attempt is {group, status: planned|completed|failed, failure?}. Failed attempts retain structured recovery errors before post-repair findings are collected. completed means the repair ran, not that the subsequent check passed.

fx release check covers repositories selected by manifest release policy; fx release is its compatibility name. It is read-only: it never merges, tags, publishes or deploys. Use --help for selection, absolute/relative error windows and optional version history, historical baseline and version-path overrides. Override keys must name selected repositories; use a separate invocation for multiple packages in one repo.

Each repos[] entry includes name, source, target, version_file, unmerged, note and unanswered, plus range, version_evidence, baseline_evidence and facet_coverage. source and target are the branch heads {branch, sha, date, message, version}; version is what the selected root VERSION or package metadata declares at that commit, null when unknown. target is null for a repository releasing from one branch, and both are null when the code host was not asked or did not answer, which the findings explain. unmerged is {commits, authors}: how many people's commits the source has that the target lacks, and how many people wrote them; null when not compared. To read those commits, ask the code host's own CLI for the range from target.sha to source.sha; fx repo show <repo> gives where the repository lives on the host. unanswered[] lists each question to the code host that failed as {field, reason, error}, where error retains structured recovery and field is the value left null (version_file, source.commit, source.version, target.commit, target.version, unmerged); a null without an entry means the repository declares none.

version_evidence uses the standalone version contract above. baseline_evidence is {baseline, head, commits, coverage, failures}. The default JSON summary replaces the commit array with commits_count and an omitted count; --details or explicit --fields retains the full array. Failures remain visible. Each snapshot has requested_ref, resolved_sha and declaration. Its commits include bots and merges since the caller's baseline, independently of unmerged. A version-field change, tag or source declaration does not establish an artifact build, publication or deployment. fx does not infer a next minor version.

facet_coverage distinguishes checked, incomplete, not_requested and not_applicable for declaration, version_history, baseline and errors. Error findings also retain a top-level failures array in summary output, with structured error codes, retryability and recovery steps. Detailed error candidates keep the latest metadata observation per ID; a resolved/ignored detail can follow an unresolved list result and is excluded from the fresh-issue verdict.

evidence_complete additionally covers requested facts and unanswered questions; it does not redefine ok or check coverage complete. The report's observed_at is one command-start timestamp. Absolute ranges normalize to UTC and use [start,end); relative policies share this observation time but can use different durations. The top-level range is null when per-repository ranges differ.

Evidence is grouped by check:

CI current compares the commit the build checked out, commit, with the branch head head when the platform names it. A null commit (Jenkins before jenkins-cli 0.12.0) falls back to comparing the build's start time with the head commit's time, which is a freshness heuristic, not revision verification; use the companion's build details then when the task requires an exact commit match. The full report's merge/dependency/issue evidence is available with --details.

Every errors finding includes evidence.query_context, even when authentication or collection fails or the check is not applicable. It is {repository, environment, range, observed_at, source}; source is {platform, provider, coordinate_fingerprint} or null for an unavailable or explicitly uncovered coordinate. The fingerprint preserves the provider's query identity before authentication without exposing arbitrary vars.

Sentry query fingerprints identify the configured endpoint, organization and project selector, so repository aliases for one project retain the same source identity. Repository and environment are bound separately in query_context. Other tracker providers may supply their own query fingerprint; without it, the full canonical coordinate fingerprint is retained conservatively.

For an audited retry, match the repository, environment, normalized range and non-null source identity before superseding an earlier failure; keep both observation times. A different server, organization, project or period is another query. Each attempt remains separate and is not an atomic remote snapshot.

error_evidence retains every collected candidate returned by an unresolved query and active in the range, including older issues. It carries items, range, observed_at, pages_read, has_more, optional next, coverage, failures and truncation_reason. Inspect these before treating a query as complete. fx follows pagination internally; there is no public cursor-resume flag. Keep the same absolute bounds when retrying or investigating a continuation with the companion. Lifetime first-seen comes from issue detail; lifetime_first_seen and first_seen_scope never use window/list dates as a fallback. Missing details remain unknown. list_first_seen has unknown scope and window_first_seen stays separate. count_scope: unknown prevents treating counts as newly occurring events. status_scope: current describes each item's actual status_observed_at, not state at the historical window; the aggregate status time is null. Assignee is read metadata, not a selected or newly assigned owner. The legacy verdict counts lifetime first appearances only; old regressions require separate review.

Uncovered explicit repositories yield REPO_NOT_COVERED, unmatched tags TAG_NOT_FOUND, unknown environments ENV_NOT_FOUND, and an empty checklist CHECKLIST_EMPTY. --since accepts windows such as 14d, 48h or 2w; invalid windows yield BAD_SINCE. Mixing relative and absolute bounds, missing a bound or invalid timezone-qualified timestamps yields BAD_TIME_RANGE. Missing platform responses/jobs, undated issues and builds that cannot be dated against the branch head warn rather than prove readiness. Closing notices distinguish RELEASE_FAILURES for confirmed failures, RELEASE_INCOMPLETE for missing check coverage without confirmed failures, and RELEASE_OK for complete checks without failures. Inspect evidence_complete separately for requested repository facts.

Update notices

MANIFEST_OUTDATED suggests fx sync; FX_OUTDATED suggests updating fx and refreshing installed Skill copies. These notices do not change the command result. Skill management, self-update, completion and lifecycle dispatch skip these checks.

Checks are cached for a day (fx) or an hour (manifest), run with two-second upstream deadlines and stay silent on failure. Local cache access and bounded npm Registry discovery are outside that deadline. FX_UPDATE_CHECK=0, update_check: false or --quiet disables them; doctor then marks those checks as not checked. A failure before configuration is loaded performs no update check.

self info exposes the effective registry and registry_source. Runtime order is optional FX_REGISTRY, npm's package-scope setting, then npm's default setting. Discovery uses global mode, honoring user/global config and NPM_CONFIG_USERCONFIG while excluding project npmrc. Invalid chosen settings remain unresolved; internal packages never fall back to a public Registry, while the public package falls back to npmjs. Historical tarball URLs are not used to guess Registry APIs. Metadata authentication is delegated to npm; the private FX_REGISTRY_TOKEN override applies only with an explicit FX_REGISTRY, never to an inferred target. Self-update pins only the fx package scope, preserving npm's default route for other dependencies.

Initialization and synchronization

fx sync — items[] of repository rows (exceptions only in summary JSON), then summary and stages (services, docs, skills, hooks, mcp, tools) in the same envelope. Failed repository rows keep the display error and a failure object with category, code, message, hint, next_steps, retryable and optional handoff. Use that recovery data to decide what to retry; the other rows may already have succeeded. Exit zero can accompany partial results: inspect summary.failed, summary.unreadable and stage counts.

Interrupted Skill stages retain item status and disk observed values in stage_details.skills; package failures retain tool_install, including completed, failed and not-started rows. code: null is not success. A package row with phase: version and code: 0 completed installation before verification failed. Inspect these records before retrying; cancellation stops execution. stage_details adds document files, Skill links/fx/tools, and tool-check, hook and MCP items where those stages ran. Rules rows are nested under stage_details.docs.rules.items. Skill tool rows retain exit code, a concise note, and the companion's structured failure when supplied. code: null means no exit result is available; consult item status and ran where supplied. A dry run executes no command, but an interrupted process may also lack an exit result. stages holds the counts; stage_details holds the rows behind them. fx init nests this result under sync; its written field confirms local registration work, not complete synchronization or readiness.

Document writes use a captured file snapshot. DOCS_WRITE_CONFLICT preserves a concurrent edit or unsafe path; inspect the path and retry from its current content. Each document row has action (the plan) and result (planned, done, skipped, failed, not_started). On failure, read files from partial stdout, or stage_details.docs.files inside sync and sync.stage_details.docs.files inside init. Completed file rows remain in the failure summary. Retry the same document operation after resolving the blocker; unchanged files are skipped. Approved foreign replacements move the original object to a unique sibling .fx-backup[-N] before a guarded write.

fx manifest render --check — exit 11 (DOCS_STALE) when the manifest repository's AGENTS.md regions differ from the manifest.

fx hook list — items[] with agent, action, activation, path, context and handoff, plus workspace/root, the effective enabled setting, and dated observations. activation: unverified means native trust/execution has not been established; a matching projection alone is not readiness. An observation whose code is HOOK_PHASE_UNREPORTED names a background phase that never answered, so its absence of findings is unknown rather than clean; run its command to find out. LOGIN_UNCHECKED likewise says every login check that did not pass was not asked or gave no answer in the background run's time, the incomplete coverage fx doctor reports; it asks for no sign-in. fx hook enable [--dry-run] enables this workspace and projects selected hosts. fx hook disable [--dry-run] disables it and removes owned entries. Global hooks / FX_HOOKS gates all workspaces; local hooks.enabled gates one. agent unpick remains global and adds per-workspace hook cleanup results. Lifecycle dispatch is an internal, fail-open host entry and is not a command to run for ordinary diagnostics.

Source contributions and recording

fx source push <paths...> --issue <id> --title <title> [--message] [--new] [--pr <id|url>] [--dry-run] returns one record with workspace, action, files, branch, base/tree/commit identities, target, target_branch, planned message/title, pull_request, findings, validated, written, fetched and retired operation IDs. Nullable fields are explicit. create, update, resume, associate, unchanged, recover, needs-fetch and cancelled are distinct actions. A preview does not write Git objects, refs or journals. --pr must resolve to the current repository and recorded source/target branches; an arbitrary URL is never used as a request destination. Private manifest addresses are permitted, credentials/personnel content are rejected, and only selected whole files enter validation and the commit.

fx manifest record-probe <repo> --env <env> --platform <platform> returns a recording record instead of a list. where --probe --record is a compatibility entry: action (preview, recorded, unchanged, skipped), file, scope, path, before/after confidence, note, row, written and handoff. The row retains the normal where/probe fields and includes probe_template. Dry-run sets after to null; only a real definite probe can set verified or not_found. Stale documents, aliases/anchors or conflicting writes are refused.

MCP

mcp list returns {items, has_more, orphaned}. mcp show <name> returns one resource with symbolic bindings, projections and readiness. can mcp:<name> optionally accepts --agent <id>; MCP resources are workspace-scoped, so --env is not applicable. Use sync --only mcp for projection and doctor for repair.

Standalone companion Skill

skill path uses the collection envelope. Each row has an optional agent, path, status (installed, not_installed, foreign), version (nullable) and version_state (matching, older, newer, unknown, missing). skill status returns embedded_version, activation: unverified and installs, which holds the same rows. Neither command needs a workspace.

Install/uninstall detect agents in the selected scope by default; --agent accepts repeated or comma-separated IDs. Path/status list all known agents unless narrowed. Project detection uses native markers; user detection also recognizes agent executables on PATH. --project selects cwd; --dir selects an independent directory and cannot be combined with --agent or --project.

Explicit install refreshes recognized copies to the bundled version, including same-version repair or replacing a newer copy. Init/sync never downgrade newer copies. Foreign replacements require confirmation and backup. Uninstall removes recognized copies after confirmation (--yes for noninteractive execution), keeps foreign paths and leaves agent selection unchanged; later sync can reinstall a copy.

skill install/update/uninstall return collection rows with action, status, version and target fields; update's action is refresh for an older copy and skip for every other target. Status is planned for previews; execution distinguishes installed, removed, not_installed, foreign, skipped, failed and not_started. On interruption, stdout retains the partial collection with each row's observed state and failure envelope; stderr preserves the original error. SKILL_FLAGS, SKILL_AGENT and SKILL_NO_AGENT are usage errors. SKILL_SOURCE_PROTECTED rejects writes through shared manifest paths; SKILL_BUSY and SKILL_TARGET_CHANGED require inspecting/retrying the target.

skill show is an explicit raw-text exception to structured stdout: it always prints the bundled SKILL.md. It makes no network check and emits no discovery hint.

Installation audit and inventory

fx tool history [tool] returns {items, has_more: false, scope: "global"} across FX_HOME. Each checkpoint has id, at, event (started, installed, finished), operation (init, install, update), nullable workspace, name, binary, via, spec, redacted vector, nullable code, version_after, binary_path, failure_code. New checkpoints also carry installation_origin and binary_path_before; legacy records can lack them and never establish original ownership. Checkpoints share an operation ID. code: 0 describes the package manager; a null version does not prove readiness. Raw process output is absent.

fx tool inventory uses the same collection envelope. Rows include name, via, spec, binary, current binary_path, recorded version_after, last_operation, last_recorded_at, installation_origin, recorded, installed_by, required_by, unknown_workspaces, state and nullable uninstall_hint. States are required, unused, unknown, unverified, not_on_path, changed, unscoped, external. Unrecorded known executables have null manager/package/version/operation fields; inspection does not adopt them. installed_by identifies successful operations, not original ownership. Only confirmed fx-origin unused rows have a removal hint; it is never an executable approval. Sync exposes these rows in stage_details.tools.installations and counts stages.tools.unused.

Service preparation

Explicit init/sync includes stages.services and stage_details.services.items. Each item has id, tool, nullable env, status, detail and optional public changes, structured failure, next_steps. Status is configured, unchanged, planned, blocked or failed; plan problems remain separate. Public configuration success never establishes personal authentication. sync --only services selects this stage, and --dry-run does not write configuration or trust.

Family companion setup uses config set-context without automatically adding --activate or --overwrite; the first-context default is owned by the companion. Inspect CONFIG_CONTEXT_CONFLICT differences and the overwrite preview before changing existing settings. Session-backed OpenObserve contexts require a new context to change their URL/scheme; login uses auth login --browser. Sentry accepts public workspace URL/org defaults and names the instance with --url; it never copies existing credentials into shared configuration. These bundled service commands need no trust approval. Vectors the team's tools.yaml patch authors do, and a changed one requires new exact-command trust.

Readiness and recovery

LOGIN_REQUIRED and non-ready can/where answers enter this flow.

login --format json includes items, has_more, summary and problems; --list includes plan problems even with --quiet. If a step needs human input or a later step throws, read the partial result on stdout as well as the error on stderr. Results distinguish handoff, blocked, failed and not_started; completed steps remain visible. After a sign-in, the same tool's earlier failed rows are checked again and blocked ones whose prerequisite now passes are attempted. A row passing on recheck is verified with a detail naming the sign-in; one still failing keeps its result and adds recheck (after, detail, optional code). Handoff rows include the required action, and service preparation rows retain available failure and next_steps fields. After resolving the blocker, repeat the same invocation: setup verifies current state before rerunning actions. Parse stdout on a nonzero exit whenever it is present. self update also captures installer output so its stdout remains parseable; inspect the returned installer code, and skill_refresh for the new installation's refresh of this Skill. tool install/update rows add skill: installed, planned, failed, not_started (an earlier Skill command could not start; the error's partial result keeps these rows), blocked (awaiting approval) or none.

Retain the original task, repository/environment and readiness query while repairing prerequisites. Authorization already given in this session persists; perform covered local work without asking again. Readiness and a printed handoff never authorize external writes, permission changes or credential creation. Cluster/Rancher restrictions apply throughout setup too.

If fx itself cannot run, follow the root guide's pre-Skill bootstrap and the manifest source README. Inspect the executable/package identity, runtime and PATH before reinstalling. A verified local node <checkout>/bin/fx.js entry can stand in for every fx command below. Do not use fx self update to recover an executable that cannot start.

1. Diagnose the selected prerequisite. Read status, handoff.summary, user_steps with each step's check, unfinished and alternatives. Use fx doctor --tool <tool> and fx login <tool> --env <env> --dry-run --no-input for current checks; --list shows recipes without verifying them. Omit --env for an unscoped tool. Load the relevant companion Skill for provider-specific setup and diagnostics. A failed auth check alone does not identify the root cause.
2. Complete authorized local preparation. For missing_tool, use the returned install/update command, preview it with --dry-run, and inspect the manager/package/registry before executing. Check ran, code, error and version_after; exit zero or a null version is not proof of readiness. Fix a confirmed PATH/runtime issue before reinstalling. For pending setup, inspect recipes via login --list and preview checks; preserve working configuration. A kind: run step can still open a browser or change remote credentials: classify its actual effects using the companion Skill. Run fx login <tool> [--env <env>] --skip-manual --no-input --yes only when all selected run effects are authorized and every patch-supplied run/check vector is already trusted or explicitly approved. --yes also trusts those vectors; it is not just a prompt suppressor. If only part is authorized, use the companion's supported scoped operation, keeping the same trust boundary. Inspect failed, blocked, skipped rows and setup problems. Bundled phase: prepare steps, such as reusing an existing login, run in fx login without --yes even with --no-input, as they do in init and sync.
3. Hand off only the human part. Prepare supported local configuration and start an authorized login flow when useful; leave QR/device/browser consent, obtaining access and new vector approval to the person. For manual/file steps, use title, instructions, open, command and expects.path when present. The file path is a destination, not permission to fetch or create credentials. Ask concisely what they must do, where, why, and name the check you will run afterward. Never request tokens in chat. Continue independent authorized work while waiting; do not claim the dependent task is complete.
4. Verify and resume. Once local input changes or the person finishes, re-run the same scoped can/where query. Login checks before acting and skips already-valid steps; do not reinstall/reinitialize successful setup. On ready, automatically continue the original task through the companion Skill. On the same unchanged failure, diagnose the specific provider error or report a concrete blocker and the missing input. Do not loop logins or ask for the same authorization again.

Concurrent manifest edits

manifest repo-set rechecks the captured document under a file lease before replacing it. If another writer changed it, the path is not a regular file, or its directory is a symbolic link, MANIFEST_EDIT_CONFLICT preserves the existing content. Inspect the real source path and retry with --dry-run; do not remove locks or overwrite another edit. An identical edit reports written: false.

Existing logins and canonical contexts

Updated family companions provide auth reuse --dry-run and auth reuse for associating a verified existing identity with the manifest's named context. Init and every explicit fx sync invoke this native preparation automatically before personal authentication; do not run it by hand inside a workspace. It never copies secrets or changes a populated destination identity. Multiple identities require --from-context after native config contexts discovery. Keep the final auth check: unavailable or unchanged does not establish login. Treat keychain/network/scope failures as their own recovery, not a login request.

Bitbucket Git transport

With a companion providing bitbucket-cli git --help, init/sync and Git remote reads use its existing login over HTTPS, including SSH URLs without SSH keys. The companion owns all credentials; never extract tokens into fx or rewrite shared manifests just to bypass SSH. Select a bootstrap account with BITBUCKET_CONTEXT; workspace Git uses the provider's context. Check actual reading with bitbucket-cli git -- ls-remote <clone-url>. API readiness alone is not proof of Git access. Old/missing companions keep ordinary Git; rejected tokens do not fall back. Push needs separate write permission. Recursive submodules are unsupported.