ワークスペースの操作

Use this reference for tasks after initialization. For preparing a new workspace or resuming its preparation, use the initialization guide.

Start with the running version

1. If the running version is not yet known, run fx self info --format json. Read SKILL.md in the returned bundled_skill directory, or run fx skill show. A global copy can be older. Keep the exact executable prefix that returned this result for every later command. The examples use fx as shorthand: if discovery used an absolute path or node <checkout>/bin/fx.js, keep using that prefix. Bare fx can resolve to a different installation after shell startup.
2. Use --format json for machine-readable results. Rediscover the bundled version when the executable changes.
3. Discover the task's resources using the routes below. For team-specific workflows, read the matching Skill from the root AGENTS.md catalog.

Global Skill installation is optional. Do not install the bundled companion into a manifest-linked team Skill directory. Installation, refresh and ownership are covered by the Skill reference.

Read a result before continuing

• init, sync, doctor, release check default to JSON summaries. omitted counts normal rows/evidence; exceptions and recovery remain. Start with the summary; use --fields for needed evidence or --details when all rows are necessary. Explicit --fields projects the full result in any format: JSON/NDJSON emit one object; human output shows selected key/value pairs. Set the view before a write; capture its output once instead of repeating the write to retrieve details.
• For init/sync/doctor, read preparation.state and preparation.scope. planned is a preview, ready is verified required work, and incomplete retains all blockers and exits 12. Follow preparation.next; next_actions are Agent work, while resume waits for changed prerequisites. Optional activation stays separate. Doctor's coverage describes diagnostics.
• For release check, inspect ok, coverage complete, warning/failure findings and repos[], what each repository would ship. It can exit zero with failures and does not publish anything. evidence_complete also covers requested declaration, version-history and baseline facts; inspect per-repository facet_coverage and structured failures before relying on missing data.
• For login, retain summary, problems and step recovery fields. handoff needs input; blocked has an unfinished prerequisite; not_started was not attempted.
• Read partial stdout after a nonzero exit. It preserves completed effects and the failed phase. Keep stderr separate and parse JSON rather than truncating it.
• For SKILL_WRITE_DENIED, inspect the denied path and preserve completed work. Continue available source analysis or sync --only repos,docs --no-refresh-manifest. Retry Skill writes only after access changes; do not move shared locks.

See report views and diagnostic fields when interpreting a result.

Execution boundaries

Use --workspace <name-or-root> to select a registered workspace directly. Use workspace list/show to discover registered roots and their health from any directory, including when manifest loading fails. Use repo list, env list, agent list, tool list, config list and member list to discover names, and fx can without a target to list capabilities. repo show and where resolve exact aliases; use canonical names for mutations. An ambiguous match is not permission to guess.

Before querying a service, use fx where <repo> --env <env> and select its capability row. Without a repository, use fx can <capability|tool> [--env <env>]. Inspect ready/status, coordinates and handoffs, then use the companion's Skill. Use execution.binary_path from the check, and its cwd, for subsequent companion calls. Checked provider commands and direct handoff vectors are already bound to that executable. Manifest-authored shell templates remain verbatim: inspect them against the returned execution evidence before use. After an update, compare its binary_path/version_after with the next readiness result and reload the matching companion Skill. Do not substitute a bare command from another shell's PATH. A printed command is not permission for a write. fx's diagnostic provider queries are read-only; source contributions use a separate explicit write workflow.

• Vectors the team's tools.yaml patch authors need exact-command trust; fx's own commands for bundled tools do not. Existing approval for that vector counts; broad setup intent does not. --yes also approves vectors, so never use it to bypass an unresolved VECTOR_UNTRUSTED decision.
• Every write supports --dry-run; preview unfamiliar effects. Respect READONLY_BLOCKED and do not add --allow-writes without authorization.
• For INPUT_REQUIRED / CONFIRM_REQUIRED, reuse already-authorized input. Ask only for a missing decision or human-only step. Foreign guide/configuration/Skill replacement needs concrete approval and a backup.
• Inspect scoped public connection settings and their provenance. Never dump environment variables, read credential stores or copy personal credentials. A blocked check is unverified, not proof that credentials are missing or expired.
• Member results belong on stdout, not in logs or shared instructions. Keep private coordinates and evaluation evidence in the team's controlled source.

Errors on stderr use {error: {category, code, message, hint, next_steps, retryable}}; only the human format on a terminal prints them as text. Follow the supplied recovery. The command reference describes output exceptions and error/coverage fields.

Recover, verify, resume

LOGIN_REQUIRED or a non-ready result enters recovery. Retain the original task and its scoped can/where query. Authorization persists across steps; a handoff does not expand it.

1. Diagnose the selected tool/environment with doctor --tool <tool> and login <tool> --env <env> --dry-run --no-input. Omit --env for unscoped tools. login --list describes recipes without verifying them. Load the companion's Skill before provider-specific setup. A scoped doctor checks/fixes only the named tools and their setup. Executable failures block dependent command checks; they do not establish missing credentials. Reuse the cause and next action already returned instead of rerunning an unchanged probe.
2. Perform authorized local preparation. Verify the package, registry and exact vectors before installation. Preserve working configuration; fix confirmed PATH/runtime problems before reinstalling. A run step may still open a browser or create credentials, so inspect its effects.
3. Hand off only what requires the person: consent, access, credentials or a new approval. Never request tokens in chat. Continue independent work while waiting. Test the requested operation first: lack of search permission does not establish that a known document cannot be read. If a Sentry instance rejects device OAuth with invalid_client, follow its token acquisition instructions rather than repeating that flow; a declared service.auth_scheme: token selects manual setup.
4. Re-run the same readiness check and resume the original task on ready. Do not repeat unchanged failures or reinitialize successful setup.

no_access means an environment is outside personal selection. not_covered means missing declared coverage. Neither establishes a remote permission denial. See detailed recovery for tool, registry, authentication and trust failures.

If fx cannot start, follow the workspace's bootstrap guidance. Inspect the entry, runtime and PATH before reinstalling. A verified node <checkout>/bin/fx.js can stand in for fx; self update cannot repair an entry that cannot execute.

Routing

For member filters, discover exact values with fx member selectors, optionally --kind area|scenario|team|function. A scenario belongs under its returned area; do not use a similarly named area as a substitute. Missing account keys are unknown, not confirmed accounts. Responsibility evidence supports a proposal; changing an existing work-item owner must still follow the user's requested scope.

Match the returned row by capability, not by a platform name from another manifest. fx can without a target lists every capability with its scope, what it is for and what serves it in this workspace. Ask about a workspace one as fx can <capability> and an environment one as fx can <capability> --env <env>.

select replaces a collection, pick/unpick add/remove names, --all follows future shared additions and --none selects nothing. Initial --repos or --no-repos applies before cloning; an init retry without them preserves selection. The manifest catalog includes repositories that are not on disk. When a task needs one, inspect it with repo show, follow its workspace-scoped next_steps to pick and sync it, and continue the original task in the returned path. Do not ask the user to learn selection commands or manually clone a known shared repository. Inspect preview coverage: remote source contents may be uninspected. status --dirty includes untracked files; dirty itself keeps its tracked-change meaning and uncommitted combines both. Use the reported workspace and empty reason.

Use --format json for results and --help for exact arguments. The table's pick/unpick notation means separate commands. Bare topics show their commands; help and completion prefer canonical names while preserving compatibility aliases. release check evaluates a checklist; it does not publish packages or deploy services.

For release preparation, set the error window explicitly when dates matter and keep the normalized [start,end) range from the report. Request version history or a historical baseline when deciding whether the written version changed; current-branch unmerged is not the range since the last release. Read all error candidates from error_evidence, not only the legacy fresh-issue list. Distinguish lifetime first-seen from window dates, and current status from historical state. Do not turn unknown count scope into new-event counts or partial pagination into absence. Use repo show responsibility evidence and scoped member queries when a team workflow needs an assignee. Team policy decides final ownership, release intent and the next version; generic evidence does not make those decisions.

What sync will and will not do

Sync clones missing repositories and fast-forwards eligible clean branches. When a different branch is checked out, it updates only the tracked branch ref. It never checks out, resets, stashes, merges or rebases. Dirty or diverged work is reported as skip_dirty / skip_diverged; inspect repository and resource outcomes. An empty upstream is skipped with outcome empty_remote; one lacking the tracked branch is skipped with no_remote_branch and still blocks readiness. Neither is a failure. An update that would replace local untracked or ignored files (for example .env) is skipped with local_files_in_the_way, lists them in files_in_the_way and blocks readiness; ask before moving them aside.

The workspace root is a plain directory. Do not initialize or run Git there. Write output that belongs to no repository under .workbench/ as the derived guide's workspace layout describes, not at the root; status returns what is left there as stray_entries. The manifest checkout is ~/.fx/workspaces/<name>/source; repo list identifies it with origin: manifest. Sync refreshes it only on a clean default branch; MANIFEST_REFRESH_KEPT means the current branch or changes were preserved. Directory/stdin sources are snapshots. A local Git source uses committed content.

Edit shared facts and team Skills in the source checkout. Team Skills live at skills/<name>/SKILL.md; changes through a managed project link also change that source. Validate with manifest lint and contribute through the verified personal fork when authorized. Never push directly to upstream. See source contribution recovery for uncertain PR creation and conditional evidence recording.

Selection and host resources

Agent selection spans all workspaces in this FX_HOME. agent unpick reconciles owned resources across them; repository/environment selection remains local. agents: [] or empty FX_AGENTS selects none. Unset both overrides to restore detection. FX_HOME does not isolate global Skill paths or companion credentials.

For manifest inspection/editing, explicit --workspace/FX_WORKSPACE wins over source discovery around cwd. An unknown explicit name fails. Inspect the selected source before editing. Tool operations use that workspace's merged baseline/patch; tool install/update require names or --all. Inventory/history span all FX_HOME.

Start hosts at the workspace root. A Skill/hook/MCP projection does not establish native activation or trust. hook list reports support and dated observations; mcp show reports references, not secret values. Hooks refresh only the bounded manifest/docs/Skills/readiness subset and never sync business repositories or approve trust. Use sync --only docs,skills when root hooks are unavailable. The tested Grok 1.0.25 host requires a Git root for project hook discovery; keep using the plain workspace root and explicit sync.

Tools, service settings and updates

Init installs only missing, enabled tools explicitly marked install_on_init. This can write to a global package prefix. Existing binaries are preserved; ordinary sync never installs packages. tool_install and history distinguish installation from version verification. Inventory's unused is a suggestion, never uninstall authorization; inspect unregistered projects before removing anything manually.

Service declarations contain public connection settings and authentication methods, never personal credentials. The method is the default for a context fx creates; a context that already reaches the declared service is ready however it signs in. Init/explicit sync prepare them before repository queries; background hooks only check. Conflicts preserve existing settings. Follow the service reference for native context conflicts and scoped login.

self info reports the Registry fx updates from and its registry_source; update notices explains how it is chosen. FX_OUTDATED and MANIFEST_OUTDATED are advisory. Update within the user's scope, then rediscover the running version and read its bundled Skill. fx self update refreshes the installed copies of this Skill; fx skill update does so on its own.