agent-profile-kit 0.204.1

package/docs/guides/workspace.md

@@ -0,0 +1,635 @@
+# Agent Profile Kit Workspace guide
+
+Agent Profile Kit keeps your reusable, cross-project agent material in one
+Workspace. The Workspace is the single canonical source. Profiles select a flat
+set of portable artifacts for a kind of work. The Installer installs each bound
+Profile into explicitly bound projects as disposable, Host-native output.
+Supported Hosts then load that material through ordinary project discovery.
+
+Keep project facts in the relevant project repository. Keep Host preferences,
+authentication, credentials, and machine-specific values outside the Workspace.
+Edit Workspace files and Local Configuration directly.
+
+## Universal Workspace material
+
+Source ownership and managed delivery are separate:
+
+- The **Workspace** may canonically own both Profile-selected artifacts and
+  **unselected universal** artifacts (material useful across every directory or
+  kind of work, not only one Profile’s selection). Leaving an artifact unselected
+  by every Profile does not make it invalid and does not move its canonical
+  source into Host configuration.
+- **Profiles** select the artifacts scoped to a kind of work for Agent Profile
+  Kit–managed project-bound delivery. A Project Binding selects a project root,
+  one Profile, and Hosts; only selected (and Dependency-resolved) artifacts from
+  that Profile enter Installation Receipts and the managed lifecycle
+  (`status`, `update`, and `uninstall`).
+- Agent Profile Kit v1 does not install, project, synchronize, or remove material in
+  personal/global Host roots. Global Host delivery is not APK-owned state: it is
+  outside Project Bindings and Installation Receipts, and `update` / `uninstall`
+  never adopt, record as managed output, or mutate those paths. `status` does not
+  treat global roots as managed output.
+- You may still manage native global delivery yourself—for example by symlinking
+  a Host Skill root entry to canonical Workspace source—but that delivery is
+  user-managed Host configuration, not Agent Profile Kit–owned state. Agent
+  Profile Kit never adopts, tracks, or uninstalls those global paths.
+- A Skill may be both universally delivered through Host configuration and
+  selected into a bound Profile. The Host owns discovery, precedence,
+  deduplication, collision diagnostics, and resolution between those sources.
+  Agent Profile Kit blocks only an exact planned destination it cannot safely
+  own, not same-identity material elsewhere.
+
+## Initialize
+
+`apkit init` creates an empty, schema-versioned Workspace at the
+fixed default path `~/.agents/agent-profile-kit/workspace/` and a version-2
+machine-local Local Configuration at `~/.agents/agent-profile-kit/config.yaml`
+that explicitly records that path when Local Configuration is absent. Pass one
+explicit absolute or home-relative path to choose another destination:
+
+```sh
+apkit init ~/projects/agent-profile-workspace
+```
+
+When Local Configuration is absent, an explicit missing or empty non-symlink
+destination is fully scaffolded and recorded. A valid existing Workspace,
+including a symlink alias, is adopted without changing its source. Rerunning is
+safe: it never overwrites the Workspace or current configuration, and it does
+not restore optional scaffolding that you removed from a valid Workspace.
+
+To keep the Workspace as an independent Git repository elsewhere, set the
+required `workspace` field in Local Configuration to one existing absolute or
+home-relative path that already contains a valid `workspace.yaml`:
+
+```yaml
+schema_version: 2
+workspace: ~/projects/agent-profile-workspace
+bindings: []
+```
+
+Symlinks are supported; relative paths and wildcards are not. When Local
+Configuration already selects a Workspace, an explicit `init <workspace>` path
+must resolve to that same canonical directory, including through an alias;
+otherwise initialization fails closed without changing either source or
+configuration. Zero-argument `init` validates the selected custom path and does
+not create, move, copy, adopt, or repair it. Initialization never migrates
+Workspace source automatically.
+
+The current Workspace schema version is 1. Its root `workspace.yaml` contains
+only `schema_version: 1`. Local Configuration schema version is 2 and its
+`workspace` field is required.
+
+### Legacy Local Configuration migration and version compatibility
+
+Version-1 Local Configuration without `workspace` is supported only as migration
+input. Run `apkit init` to upgrade it before using `validate`, `status`, `update`,
+`install`, or `uninstall`. Those commands never migrate
+the file implicitly: they fail closed with actionable `apkit init`
+guidance while leaving migration to the explicit `init` command.
+
+For a legacy file that omitted `workspace`, migration records the conventional
+default `~/.agents/agent-profile-kit/workspace/`. For a legacy file with an
+authored path, migration preserves that path. `init` validates the selected
+Workspace before atomically replacing only Local Configuration, preserving
+Project Bindings, comments, line endings, and file mode; it never moves or
+rewrites Workspace source. If validation fails, the configuration remains
+unchanged.
+
+Before migrating, make and retain a copy of the version-1 Local Configuration:
+
+```sh
+config_dir="$HOME/.agents/agent-profile-kit"
+cp -p "$config_dir/config.yaml" "$config_dir/config.yaml.before-schema-v2"
+```
+
+Keep this backup until the current CLI has been validated in normal use.
+To roll back to an older binary that understands only version-1 configuration,
+stop using the current CLI, restore the copy, and run that older binary:
+
+<!-- historical-command-excerpts:start -->
+```sh
+config_dir="$HOME/.agents/agent-profile-kit"
+cp -p "$config_dir/config.yaml.before-schema-v2" "$config_dir/config.yaml"
+agent-profile-kit validate
+```
+<!-- historical-command-excerpts:end -->
+
+The restored file preserves the pre-migration Workspace selection and Project
+Bindings. This reverses only the Local Configuration schema transition; it does
+not undo later Workspace content changes.
+
+### Required structure vs initialization scaffolding
+
+A valid Workspace needs only a supported `workspace.yaml`. That Manifest is the
+Workspace marker. Missing artifact directories are treated as empty categories;
+present ones are validated and ingested normally. `README.md`, `AGENTS.md`, and
+`.gitignore` are optional user-owned files that the engine never requires.
+
+When creating a **new** Workspace, `init` still scaffolds a friendly layout so
+you can discover where material belongs:
+
+- artifact directories `profiles/`, `context/`, `skills/`, `agents/`, `hooks/`,
+  and `tools/` (with `.gitkeep` placeholders)
+- a bindable `profiles/example.yaml` and its `context/example-context.md`
+- short bootstrap `README.md` and `AGENTS.md` pointers to the current guides
+- a starter `.gitignore`
+
+The example gives a new user one complete `install` → `status` → `update` path.
+Delete both `profiles/example.yaml` and `context/example-context.md` together,
+unused empty directories, or bootstrap docs if you prefer a minimal tree;
+later `init` runs do not restore removed optional scaffolding; validation,
+status, update, and uninstall keep working. Do not treat generated Host
+output as source material.
+
+## Author the Workspace
+
+This release supports Profile Context and Context Modules for Antigravity,
+Codex, Claude Code, Grok, OpenCode, and Pi, and portable Skills for Antigravity,
+Codex, Claude Code, Grok, OpenCode, and Pi. Antigravity Context uses `.agents/rules/`;
+Antigravity, Codex, OpenCode, and Pi Skills install through the qualified shared
+`.agents/skills/<Artifact ID>/` projection after project-surface capability checks;
+Pi and OpenCode resolve other Skills, extensions, and packages through native
+Host behavior.
+Disabled model-invocation Skills are projected with the shared
+`disable-model-invocation: true` field while explicit `/skill:<Artifact ID>`
+activation (or OpenCode `/<Artifact ID>` command activation) remains available.
+Profiles contain only `id`, `context`, and `skills`; Agents, Hooks, and Tools
+are not delivered by this release. A Profile must select at least one supported
+artifact overall (Context Module, Skill, or both); no individual category is
+mandatory. Context-only, Skills-only, and combined Profiles are valid.
+
+A Context Module is a Markdown file under `context/` with frontmatter containing
+one stable, lowercase kebab-case `id`; the Markdown body is the Context. A Skill
+is a standard Agent Skills package under `skills/`, rooted at `SKILL.md`; its
+standard `name` is its stable Artifact ID. The frontmatter needs a lowercase
+hyphenated `name` and a non-empty `description`. Scripts, references, and assets
+remain ordinary standard Skill content. If a Skill needs Agent Profile Kit-only
+dependency metadata, put it in an optional `agent-profile-kit.yaml` sidecar.
+
+### Skill model-invocation policy
+
+By default, Hosts may invoke a Skill implicitly when the model matches its
+description. To require explicit user invocation while keeping the Skill
+available on request, set optional standard namespaced metadata:
+
+```yaml
+metadata:
+  agent-profile-kit.model-invocation: disabled
+```
+
+Accepted values are the strings `allowed` and `disabled`. Absence normalizes to
+`allowed`. Invalid types or values fail at Workspace ingestion.
+
+This is the only portable spelling. Host-native top-level
+`disable-model-invocation` and Codex-only `agents/openai.yaml` policy are not
+canonical source fields for Agent Profile Kit: migrate Host-shaped Skills to
+the namespaced metadata key above rather than relying on Host-specific
+frontmatter. The Installer never rewrites Workspace `SKILL.md` during
+validate, status, or update.
+
+Adapters translate the trusted policy only in generated Host output:
+
+| Canonical policy | Claude / Grok generated output | Antigravity / Codex / OpenCode / Pi shared output |
+| --- | --- | --- |
+| `allowed` (default) | No Host restriction field | No Host restriction field |
+| `disabled` | `disable-model-invocation: true` in generated `SKILL.md` | `disable-model-invocation: true` in generated `SKILL.md` plus `policy.allow_implicit_invocation: false` in generated `agents/openai.yaml` and `"permission": { "skill": { "<id>": "deny" } }` in generated `.opencode/opencode.jsonc` |
+
+Existing source `agents/openai.yaml` content is preserved. An equivalent
+invocation policy coalesces; malformed, wrong-type, or conflicting policy
+produces one structured project Blocker naming the Workspace and shared
+Host-policy authorities with a Workspace repair remedy before any project write. Generated
+policy fields carry short deterministic comments. When any selected Skill
+disables model invocation, update-time capability probing checks each selected
+Host's enforcement floor: Claude Code CLI
+`2.0.64+` (same floor as unscoped rules and native Skill discovery, which
+honors `disable-model-invocation`), Grok CLI `0.2.0+` (same floor as project
+rules and native Skill discovery, which honors `disable-model-invocation`),
+Codex CLI `0.99.0+` (first stable release with `agents/openai.yaml`
+`policy.allow_implicit_invocation`; see openai/codex#11244 / rust-v0.99.0),
+OpenCode CLI `1.18.23+` (filters denied Skills from model inventory while
+leaving native command activation available), and Pi CLI `0.82.1+` (honors
+`disable-model-invocation: true` in `SKILL.md`).
+OpenCode records `native-project-instructions-skills-invocation-v1` for
+explicit-only Skill enforcement or `native-project-instructions-skills-v1` for
+baseline allowed Skills. Pi records `native-project-shared-skills-invocation-v1`
+for Skills-only or `native-project-append-system-shared-skills-invocation-v1`
+for combined Profiles. Antigravity records `native-project-shared-skills-invocation-v1`
+or `native-project-always-on-rules-shared-skills-invocation-v1` for the same two
+shapes. Probing is advisory: an older, missing, or unreadable CLI produces a
+warning, and the planned policy fields are written regardless — the Adapter
+never silently omits or weakens what it plans.
+
+Artifacts may declare required Dependencies with explicit typed references. Put
+Context Module Dependencies in their frontmatter and Skill Dependencies in each
+Skill's Agent Profile Kit sidecar. Each reference contains `type` (`context` or
+`skill`) and its stable `id`. Dependencies are resolved transitively and every resolved reason remains
+available in live planning. Inclusion reasons are not
+persisted in Installation State.
+
+A Profile is a YAML file under `profiles/` with exactly an `id`, a `context`
+array, and a `skills` array. At least one of `context` or `skills` must be
+non-empty. A Skills-only Profile installs only selected Skill packages for Hosts that
+support them and Installer lifecycle metadata—no Context snapshot, Codex
+SessionStart hooks, or Claude Context rule. Antigravity Skills-only bindings
+check only the shared `.agents` and `.agents/skills` surfaces. Host capability
+probing is scoped to the selected categories (Skills-only does not require Context
+machinery). Profiles do not inherit, use wildcards, or carry Host settings.
+
+```md
+---
+id: engineering-rules
+dependencies:
+  - type: context
+    id: security-rules
+---
+Keep project facts in the project repository.
+```
+
+```yaml
+# skills/review-pr/agent-profile-kit.yaml
+dependencies:
+  - type: skill
+    id: write-release-notes
+```
+
+```yaml
+id: coding
+context:
+  - engineering-rules
+skills:
+  - review-pr
+```
+
+```md
+<!-- skills/review-pr/SKILL.md -->
+---
+name: review-pr
+description: Review a pull request. Use when asked to review code changes.
+---
+
+# Review a pull request
+```
+
+```md
+<!-- skills/to-spec/SKILL.md — explicit-only invocation -->
+---
+name: to-spec
+description: Turn the current conversation into a spec.
+metadata:
+  agent-profile-kit.model-invocation: disabled
+---
+
+# To spec
+```
+
+## Bind projects in Local Configuration
+
+Project Bindings live only in machine-local
+`~/.agents/agent-profile-kit/config.yaml`. Each binding names exactly one
+existing absolute or home-relative project root, one Profile, and a non-empty set
+of supported Hosts (`antigravity`, `codex`, `claude`, `grok`, `opencode`, `pi`). Host order
+and duplicate entries normalize at ingestion. There are no wildcards, recursive scans,
+hidden default projects, Host auto-detection, per-session Profile selection, or
+Profile version pins. A project root may appear in only one binding.
+
+Hand-edit `config.yaml`, or record one binding and install it in one action
+with `apkit install` (confirms interactively; `--auto-confirm` answers it):
+
+```sh
+apkit install coding --host codex --auto-confirm
+apkit install coding ~/projects/tools/agent-profile-kit --host antigravity --host codex --host claude --host grok --host opencode --host pi --auto-confirm
+```
+
+Omit the project argument to use the current working directory. At least one
+`--host` flag is required. An identical installation is left unchanged; a different
+Profile or Host set for the same project replaces the installation in the same
+action. Do not
+hand-edit `config.yaml` while `install` is running: cooperating lifecycle commands
+serialize, but a text editor does not participate in that lock. Installing a
+Profile also verifies its generated output; run `validate` for Workspace checks
+and `status` to review installation state.
+
+Remove one installation and forget its recorded selection with an explicit scope:
+
+```sh
+apkit uninstall --here --auto-confirm
+apkit uninstall --project ~/projects/tools/agent-profile-kit --auto-confirm
+```
+
+Scope is explicit (`--here`, `--project <path>`, or `--all`, mutually exclusive); add `--profile <name>` to intersect, `--remove-changed` to authorize deletion of independently changed generated files, and `--auto-confirm` to answer the confirmation non-interactively. Existing
+paths use the same canonical-root rules as bindings, including symlink aliases.
+When a project no longer exists, `uninstall --project` still forgets its selection only when the
+argument exactly matches its authored `project` spelling; it never guesses an
+alias. A fully removed Project is forgotten only after its output removal succeeds, so a later `update` does not reinstall it. Cooperating lifecycle commands
+serialize; do not hand-edit the file concurrently.
+
+```yaml
+schema_version: 1
+bindings:
+  - project: ~/projects/tools/agent-profile-kit
+    profile: coding
+    hosts:
+      - codex
+      - claude
+  - project: /Users/you/work/customer-portal
+    profile: coding
+    hosts:
+      - claude
+```
+
+## Validate, status, and update
+
+For Codex bindings that select Context, the Adapter requires Codex CLI 0.145.0 or
+newer so the generated SessionStart handler can deliver the complete Context
+envelope without Codex's default head-and-tail spill. Host capability probing is
+advisory: during `update`, an older, missing, or unreadable Codex CLI produces a
+warning while the planned project and Installation State writes proceed
+regardless. `status` performs no Agent Host process execution and no capability
+probing; a Project-scoped `status` or `update` plans only its
+selected binding. `update --all` writes every selected Project including any with
+Host capability warnings; global Blockers still stop every fleet write.
+Skills-only Codex bindings do
+not require this floor. Review and trust the generated project SessionStart hook
+in Codex for each bound project. Lifecycle hooks are enabled by default. Agent Profile Kit checks the effective global and project configuration
+during update and warns when hooks are explicitly disabled, when relevant
+configuration is malformed or unreadable, or when `hooks` or the deprecated
+`codex_hooks` alias is not a boolean. These warnings do not block installation,
+but generated Context may not load until the setting is corrected. Project configuration takes
+precedence over global configuration. If `CODEX_HOME` is set, Codex reads its
+global configuration from `CODEX_HOME/config.toml`; otherwise it uses
+`~/.codex/config.toml`. Skills-only Codex bindings do not require hooks.
+
+Run `apkit validate` to check the Workspace and every Project Binding.
+Review the concise read-only reconciliation outcome with
+`apkit status`. It leads with whether reconciliation can proceed,
+groups changes and blockers by Profile Installation, and summarizes
+changed file paths with `+`, `~`, `-`, or `!` markers without listing unchanged
+output. Long lists are capped with an overflow pointer to `--verbose`.
+Non-current Profile Installation states such as `stale source`, `blocked`, or
+`removal` get a short explanation when present (once per distinct state across
+installations). Pending Git exclusion work appears as one concise clause; exact
+targets and path changes are reserved for `--verbose`. When action is
+useful, concise results end with one next-action line derived from the same
+attention surface as the report body: actionable `status` points directly to the
+matching update command; a ready fleet `status --all` recommends `update --all`; a
+blocked result tells you to resolve the reported blocker and retry the same
+command you just ran; current status and completed or no-op `update` results omit
+a next step. `status` and `update` target the complete fleet by default. Narrow
+the scope with `--here` for the bound Project containing the current working
+directory, one explicit existing absolute or home-relative bound Project root,
+or `--project <path>`; `--all` states the fleet scope explicitly. Scoped
+planning, Git and ownership inspection, reconciliation, reports,
+and writes exclude unrelated Projects; a shared Git exclusion file changes only
+through the selected installation's contribution-aware union. Host capability
+probing is advisory and happens only during `update`: a missing or outdated Host
+CLI produces a warning and the planned output is written regardless; capability
+problems never block application and do not mark generated files as drifted.
+
+`apkit update` refreshes the installed Context and Skills in your Projects from
+the Workspace; it does not upgrade the `apkit` executable itself.
+
+For focused per-output and state diagnostics, append `--verbose` to `status` or `update`. Warnings, blockers, drift reasons, and removal
+intent remain visible in the concise view. Git-tracked-path blockers explain
+that repository-owned content is not replaced because generated Profile
+Installation output must be exclusively Installer-owned.
+
+Git is optional. For a Git binding, `update` installs only into the exact bound
+project directory. The Installer uses Git for tracked-path protection and local
+exclusions but does not inspect or report worktree topology. Bind any additional
+root explicitly only when Hosts must be launched directly from that root; it
+then follows the same lifecycle as any other binding.
+
+For every bound project root, the ordinary removal order is:
+
+```sh
+apkit uninstall --project /path/to/project --auto-confirm
+# Now delete the project directory.
+```
+
+If the project directory was deleted first, run `uninstall --project` with its exact authored
+path. That explicit action confirms the deletion was intentional; it forgets the machine-local selection without attempting
+project filesystem deletion and cleans any separately surviving local Git
+exclusions whose ownership was recorded. Restoring the project later requires a
+new `install`.
+
+Generated output is owned whole: complete files and artifact directories whose
+Installation Receipt proves Agent Profile Kit ownership, with the receipt's
+recorded hashes providing the continuity evidence that extant material is what
+Agent Profile Kit last published. Generated instructions open with a short
+notice stating that apkit generated them, that lasting edits belong in the
+Workspace, and that `install`, `update`, and `uninstall` replace or remove an
+independently changed generated file only with your explicit consent. The
+claimed OpenCode configuration file carries the same generated-source notice
+with project-file guidance instead of the Workspace pointer. Supporting Skill
+resources keep their bytes. See ADR-0041. Unrelated project files,
+repository-owned instructions, global Host configuration, authentication, trust,
+approvals, plugins, and sessions remain untouched. Agent Profile Kit does not
+merge selected fields into Host or repository configuration, install a watcher or
+Git hook, or modify shared `.gitignore` files.
+
+For a currently bound installation, `update` recreates a
+recorded output that is completely missing when normal path-conflict checks
+pass. Modified output is ordinary refresh work while at least one recorded root
+still matches its recorded hash; when no recorded root matches, ownership
+continuity cannot be proven and `status` blocks until you restore or remove the
+generated files. Unexpected directory members are never overwritten.
+
+## Use Hosts natively
+
+After `update`, launch Antigravity, Codex, Claude Code, Grok, OpenCode, or Pi from the
+bound project the way you normally would. Agent Profile Kit does not manage their
+authentication, trust, approvals, plugins, or sessions, and does not launch
+Hosts.
+
+### Antigravity
+
+Antigravity receives Profile Context through deterministic always-on rules under
+`.agents/rules/`. The Adapter requires `agy` CLI 1.1.13 or newer and writes one
+rule for the Profile envelope followed by one complete rule per Context Module.
+Each generated rule contains `trigger: always_on` frontmatter and must stay at or
+below 12,000 characters. If one Context Module is too large, status reports a
+structured blocker instead of truncating it.
+
+Antigravity discovers the rules from the current bound project; you do not need
+to create or select an Antigravity Project. Trust is Host-owned: after `update`,
+trust the bound project in Antigravity if it asks. Agent Profile Kit does not
+read or change trust, settings, authentication, plugins, Project records,
+`AGENTS.md`, or `GEMINI.md`. A standing trust reminder appears for every
+non-empty Antigravity plan, but unproven trust never blocks safe writes.
+
+Antigravity also discovers selected Skills through the qualified shared
+`.agents/skills/<Artifact ID>/` projection used by Codex and Pi. The complete
+package preserves standard members — with the generated-source notice opening
+each `SKILL.md` body after frontmatter (ADR-0041) — and, for disabled Skills,
+both the generated `disable-model-invocation: true` field and Codex
+`agents/openai.yaml` policy.
+Antigravity's native discovery, trust, settings, and effective inventory remain
+Host-owned.
+
+### Codex
+
+Codex receives the complete Profile Context through a native project SessionStart hook and
+discovers selected Skills under `.agents/skills/<Artifact ID>/`. When Context is
+installed, Codex asks you to review the generated hook: review its contents and
+approve it when they match the expected SessionStart behavior, because declining
+it prevents Profile Context from loading. Before launching Codex,
+trust each bound project in Codex — project trust is Host-owned and is not
+configured by Agent Profile Kit.
+Ordinary launches from a Git project's bound directory or its descendants receive
+that material. For a non-Git project, launch Codex from the exact bound root;
+launching from a descendant prevents Profile Context from loading. Skills-only
+Codex Profiles generate no hook and require no hook approval.
+
+### Claude Code
+
+Claude Code receives Profile Context as an unscoped owned project rule under
+`.claude/rules/` and discovers selected Skills under
+`.claude/skills/<Artifact ID>/`. Ordinary Claude launches in the bound project
+load that material. Claude project rules do not depend on Git.
+
+### Pi
+
+Pi receives Profile Context through the owned project file
+`.pi/APPEND_SYSTEM.md`. The Pi Adapter requires CLI 0.82.1 or newer and
+proves that `.pi` and the append-system destination are compatible before
+Context writes; Skill-bearing Profiles instead prove the shared `.agents` and
+`.agents/skills` surfaces. Profiles with portable Skills receive one shared
+package per resolved Artifact ID under `.agents/skills/<Artifact ID>/`;
+standard package bytes and modes are preserved apart from the generated-source
+notice that opens each projected `SKILL.md` body (ADR-0041), and
+`agent-profile-kit.yaml` is omitted. Codex and Pi co-own one normalized package when both are selected;
+the package carries every required Host policy field without adding consumer
+metadata to Skill source. Pi owns Skill resolution across personal, project,
+ancestor, package, extension, and configured sources. Disabled
+model-invocation Skills receive top-level `disable-model-invocation: true` in
+generated `SKILL.md` while the canonical Workspace source remains unchanged
+and explicit `/skill:<Artifact ID>` activation remains available. Malformed or
+unreadable relevant settings warn without blocking. Pi's native project trust,
+authentication, settings, prompt files, and per-session overrides remain
+Host-owned.
+
+### OpenCode
+
+OpenCode receives Profile Context through the owned composed Context document
+at `.agent-profile-kit/opencode/context.md` and references it through the
+additive `instructions` list inside the claimed configuration file at
+`.opencode/opencode.jsonc`. OpenCode combines this configuration with
+user-authored slots via native additive merging, and the Project-relative
+reference continues to load Context when OpenCode is launched from any subdirectory.
+The OpenCode Adapter requires CLI 1.18.23 or newer. When configuration is planned
+(Context or disabled Skills), the Adapter emits one transition launch-constraint
+Host Setup Step tied to `.opencode/opencode.jsonc` reminding you to restart
+running OpenCode sessions.
+
+OpenCode discovers selected Skills through the qualified shared
+`.agents/skills/<Artifact ID>/` projection used by Antigravity, Codex, and Pi.
+When trusted model-invocation policy is `disabled`, the OpenCode Adapter
+configures an Artifact-ID-keyed global Skill permission rule with action `deny`
+inside `.opencode/opencode.jsonc`. OpenCode filters denied Skills from the
+model-facing inventory while native Command activation (`/<Artifact ID>`)
+remains available. When Claude and OpenCode are co-selected in a Project Binding
+with Skills, OpenCode natively discovers Skills under both `.claude/skills` and
+`.agents/skills` and reports duplicate Skill names; the OpenCode Adapter emits
+one non-blocking diagnostic warning naming both roots. OpenCode's native
+discovery, configuration slots, and session commands remain Host-owned.
+
+### Precedence and conflicts
+
+Repository-owned project instructions take precedence over Profile Context on
+conflict. Agent Profile Kit does not detect or resolve contradictions in prose;
+conflicting guidance remains visible to you and the Host. Global Host
+configuration and repository-owned files stay live and unchanged.
+
+### Installation State compatibility and recovery
+
+Installation State is durable machine-local ownership evidence at
+`~/.agents/agent-profile-kit/state/manifest.json`. It is not Workspace source,
+but lifecycle safety depends on it for movement, repair, uninstall, Temporary
+Profile Installation recovery, and repository-local exclusion cleanup. Do not
+edit it by hand or reconstruct it from generated project output.
+
+Agent Profile Kit reads strict JSON at Ownership State schema versions 6 through
+9 and writes schema version 9. The writer validates
+the exact serialized bytes through the production reader before atomic rename.
+Active ordinary and temporary installations use one minimal receipt shape;
+removed temporary identities retain only the compact ID needed for idempotent
+retry. Directory receipts retain one aggregate root hash, not complete member
+trees.
+
+The pre-1.0 YAML migration window is closed. If `state/manifest.yaml` remains,
+install the shipped Agent Profile Kit 0.95.0 release, run a successful
+state-writing lifecycle command to publish `manifest.json`, and then retry with
+the current release. Current commands reject the YAML file without parsing,
+changing, or removing it.
+
+Back up current `manifest.json` with ordinary machine backup tooling. If the
+current state is missing or malformed, restore a known-good backup and retry.
+Agent Profile Kit never adopts surviving generated output or reconstructs
+ownership from it.
+
+Without a backup, stop the CLI and manually remove only project output whose
+ownership you independently verify, including any
+`.agent-profile-kit/installation.json` file left by an older version. In each affected
+`.git/info/exclude`, remove only the marked block between
+`# BEGIN Agent Profile Kit generated paths` and
+`# END Agent Profile Kit generated paths`; preserve every unrelated byte. Then
+recreate the desired Project Bindings and run `apkit update` to establish fresh
+ownership receipts. This manual path is intentionally fail-closed.
+
+### Host Resolution and project-bound Profiles
+
+This section is the Host-path detail for the
+[Universal Workspace material](#universal-workspace-material) boundary.
+
+Agent Profile Kit installs selected Skills only into the bound **project**
+(`.agents/skills/<Artifact ID>/` for Antigravity, Codex, OpenCode, and Pi,
+`.claude/skills/<Artifact ID>/` for Claude, `.grok/skills/<Artifact ID>/` for
+Grok). Antigravity Profile Context uses `.agents/rules/` alongside its shared
+Skill packages. It never installs into, adopts, disables, or removes
+personal/global Host Skill folders. Unselected Workspace
+Skills are not installed into projects either; they may remain valid Workspace
+source without any APK-managed delivery.
+
+Those global folders remain Host-owned:
+
+- Codex: `~/.agents/skills/` and `~/.codex/skills/`
+- Claude Code: `~/.claude/skills/`
+- Grok: `~/.grok/skills/` (plus enabled compatibility roots and configured
+  `[skills].paths`; see `grok inspect`)
+- OpenCode: personal/global configured directories
+- Pi: `~/.pi/skills/` (plus configured sources)
+
+Selected Skills may share an identity with material from these roots, packages,
+plugins, extensions, compatibility sources, or other Host-native locations.
+The Host owns discovery, precedence, deduplication, collision diagnostics, and
+resolution across those sources. Agent Profile Kit neither scans an effective
+inventory nor asks you to remove same-identity material.
+
+Where a disable is detectable without reconstructing Host Resolution, the
+Adapter warns: Codex checks SessionStart hooks and Grok checks
+`[skills].disabled` and `[skills].ignore`. Malformed or unreadable
+configuration that an Adapter reads for planned output also warns; Pi's
+settings rule is described in its Adapter section above. Capability failures,
+unrepresentable portable semantics, and exact Output Ownership Conflicts at the
+planned project destination remain blockers.
+
+## Status and uninstall
+
+Use `apkit status` for the bound Project containing the current directory, pass
+one explicit Project root, or use `apkit status --all` to inspect every binding.
+It reports current, not installed, stale source, drifted output (including wholly absent
+owned output), malformed ownership, and blocked installations, while keeping Host
+configuration warnings visible.
+
+Use `apkit uninstall --here`, `uninstall --project <path>`, or `uninstall --all` (with `--auto-confirm` non-interactively, plus `--profile <name>`, `--host <host>`, and `--remove-changed` as needed) to remove selected installations and forget their recorded selection. `--host <host>` (repeatable) removes only those Hosts within the scope while the remaining Hosts keep working. It removes only Installation Receipt-proven output and preserves the Workspace and unselected Projects. It writes no teardown provenance. Because a fully removed Project is forgotten, the next `status` no longer selects it, rather than reporting it as unsafe unexplained missing output.
+
+To stop managing a Project but keep its Git-owned files in place, remove its entry from `~/.agents/agent-profile-kit/config.yaml` by hand; the next `update` reconciles the leftovers. Neither path modifies personal/global Host configuration or repository-owned files.
+
+Review personal content before publishing this Workspace. Agent Profile Kit does
+not classify private material, and credential values do not belong in a Workspace
+regardless of whether you publish it.
+
+For the complete human guide, run `apkit guide --full`.
+For help authoring with an agent, run `apkit guide --agent`.
+For a short copyable example, run `apkit guide profile`, `apkit guide context`,
+or `apkit guide skill`.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agent-profile-kit",
+  "version": "0.204.1",
+  "description": "Compose portable agent material into host-native profiles.",
+  "type": "module",
+  "bin": {
+    "apkit": "./dist/cli.js"
+  },
+  "files": [
+    "dist/cli.js",
+    "docs/guides",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run typecheck && bun run build:bundle",
+    "build:bundle": "bun build cli/index.ts --target=node --packages=bundle --outfile=dist/cli.js --silent",
+    "test": "bun run test/support/suite-supervisor.ts full",
+    "test:focused": "bun run test/support/suite-supervisor.ts focused",
+    "test:fleet": "bun run test/support/suite-supervisor.ts focused test/fleet-qualification.test.ts",
+    "test:stress": "bun run test/support/suite-supervisor.ts stress",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepack": "bun run build"
+  },
+  "engines": {
+    "node": ">=22 <23",
+    "bun": "1.4.0"
+  },
+  "os": [
+    "darwin"
+  ],
+  "devDependencies": {
+    "@types/bun": "^1.4.0",
+    "@types/node": "^26",
+    "@types/prompts": "^2.4.9",
+    "prompts": "^2.4.2",
+    "smol-toml": "^1.8.0",
+    "typescript": "^7.0.2",
+    "yaml": "^2.9.0"
+  }
+}