persona-harness 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -14,6 +14,20 @@ preparation alone does not establish stable support or channel state.
   explicit subsequent `ph update enable --yes` can opt in; malformed, foreign,
   symlinked, or user-diverged state remains fail-closed and unchanged.
 
+## [0.9.1] - 2026-08-31
+
+- Publish the canonical portable-host guide for the static adapters generated
+  by `ph init` in Codex, Claude Code, OpenCode, and Antigravity projects.
+  It distinguishes package-created discovery files from a live host session's
+  selection or delivery of a skill.
+- Document safe adapter ownership and update behavior: a later `ph init` may
+  refresh only unchanged Persona-owned files, while modified, user-owned, or
+  symlinked targets remain fail-closed. `ph update enable` remains the separate
+  optional OpenCode plugin-pin path.
+- Keep Context and legacy runtime injection default-off, and state that current
+  Context delivery is an optional OpenCode-specific runtime boundary rather
+  than a portable-host claim.
+
 ## [0.8.31] - 2026-08-25
 
 - Clarify `ph workflow finish implement` source-read runtime failures with a

package/README.md

@@ -6,7 +6,7 @@
 
 # Persona Harness
 
-**Evidence-first completion gates for AI coding agents building Java/Spring backends.**
+**Evidence-first workflow gates and portable skill adapters for AI coding agents building Java/Spring backends.**
 
 [![npm version](https://img.shields.io/npm/v/persona-harness?color=369eff&labelColor=black&style=flat-square)](https://www.npmjs.com/package/persona-harness)
 [![npm downloads](https://img.shields.io/npm/dt/persona-harness?color=ff6b35&labelColor=black&style=flat-square)](https://www.npmjs.com/package/persona-harness)
@@ -45,9 +45,10 @@ completion in 5/5 measured runs. Runtime injection did not improve the paired
 OpenCode measurements and added cost, so it remains default-off.
 
 **Built for:** Java/Spring/Gradle projects with explicit workflow gates and
-evidence checks. `ph init` also materializes portable skill adapters for Codex,
-Claude Code, OpenCode, and Antigravity; live host selection and delivery remain
-separate observation boundaries.
+evidence checks. `ph init` materializes portable, project-local skill adapters
+for Codex, Claude Code, OpenCode, and Antigravity. Static adapter installation
+is package behavior; a host's live skill selection and delivery are separate
+observation boundaries.
 
 **Not a promise of:** automatic implementation, generated-app quality,
 production readiness, token savings, or broad security guarantees.
@@ -105,8 +106,9 @@ Persona Harness exposes two deliberately separate tracks:
   verification authority.
 - **Isolation:** Context-only paths do not execute project commands or contact
   GitHub/network.
-- **Host:** OpenCode is the only implemented delivery adapter; live host
-  delivery remains a separate, unobserved boundary.
+- **Host:** `ph init` installs static skill adapters for Codex, Claude Code,
+  OpenCode, and Antigravity. Context delivery is currently implemented only by
+  the optional OpenCode adapter and remains a separate, unobserved boundary.
 - **Evidence:** Context usefulness remains `INCONCLUSIVE` until independent
   external evidence exists.
 - **Product focus:** the productized workflow focus is Java/Spring. The
@@ -214,18 +216,22 @@ earned by measurement first — see [MEASURED-CLAIMS](docs/MEASURED-CLAIMS.md).
 
 ## Install
 
-Requires Node.js ^20.17.0 || >=22.9.0 (Node 21 is unsupported), Java 21+ / Gradle, and the OpenCode CLI with a configured provider.
+Requires Node.js ^20.17.0 || >=22.9.0 (Node 21 is unsupported). Java 21+ /
+Gradle are required for the Java/Spring workflow rail. Install the coding-agent
+host you already use separately; OpenCode is optional unless you want its
+plugin-only Context delivery.
 
 ```bash
-# OpenCode
-curl -fsSL https://opencode.ai/install | bash   # or: npm install -g opencode-ai
-opencode auth login
-
-# Persona Harness
+# Any supported host project
 npm install -D persona-harness
-npx ph --help && npx ph doctor
+npx ph init
+npx ph doctor
 ```
 
+`ph init` installs host-native discovery files without requiring a
+Persona-specific launch command. See the [portable host adapter guide](docs/current/portable-host-adapters.md)
+for the generated paths, host-specific limits, and safe update procedure.
+
 ## Quick Start
 
 For a clean project directory (not the Persona Harness repo itself):
@@ -241,7 +247,9 @@ npx ph go "Add a task creation endpoint."
 
 `ph init` writes manifest-owned shared-skill adapters beneath `.agents/skills`,
 `.claude/skills`, and `.opencode/skills`. It refuses a modified, user-owned, or
-symlinked generated target instead of overwriting it.
+symlinked generated target instead of overwriting it. The generated files make
+the catalog discoverable to the host; they do not prove that a running session
+selected a skill or grant a workflow command any authority.
 
 For an existing Java/Spring/Gradle project, inspect the inferred draft first,
 then accept it explicitly:
@@ -308,6 +316,11 @@ OpenCode configuration and never overwrites changed rules, profiles, workflow
 state, or `.gitignore`; malformed, symlinked, foreign, or ordinary projects are
 left unchanged.
 
+This automatic update path is OpenCode-plugin-specific. It does not rewrite the
+portable host adapter trees. After upgrading the npm package, run `npx ph init`
+to refresh only unchanged Persona-owned adapters; modified, user-owned, or
+symlinked adapter files stay blocked rather than being overwritten.
+
 > [!NOTE]
 > If `workflow finish` fails, the agent must fix the reported blocker before claiming completion. **That failure is the product working, not a bug.**
 
@@ -396,6 +409,23 @@ do not change the P0-3 root CLI discovery contract.
 
 ## Platform And Host Support
 
+### Portable host adapters
+
+`ph init` materializes the same catalog into each host's project-local discovery
+layout. This proves the installed package produced safe static files, not that a
+specific live session loaded or followed one.
+
+| Host | Project-local adapter path | What the package establishes |
+| --- | --- | --- |
+| Codex and Antigravity | `.agents/skills/persona-harness-<skill-id>/SKILL.md` | Manifest-owned, host-neutral skill discovery metadata. |
+| Claude Code | `.claude/skills/persona-harness-claude-<skill-id>/SKILL.md` | Manifest-owned, host-neutral skill discovery metadata. |
+| OpenCode | `.opencode/skills/persona-harness-opencode-<skill-id>/SKILL.md` | Manifest-owned discovery metadata; the optional plugin remains a separate runtime boundary. |
+
+The `.agents` and `.claude` adapters explicitly opt out of OpenCode automatic
+discovery so an OpenCode project receives one native candidate rather than
+duplicates. For the full ownership, upgrade, and non-claim boundary, read the
+[portable host adapter guide](docs/current/portable-host-adapters.md).
+
 ### Node runtime floor
 
 The packaged CLI and its product-owned Sigstore authority verifiers require
@@ -424,12 +454,11 @@ or provide a credential fallback. When more than one repository is enrolled,
 pass the selected enrolled `owner/repository` to `fetch github`. Neither
 command publishes a package, moves a channel, or consumes Finish authority.
 
-| Surface | Status | Evidence boundary |
+| CLI/runtime surface | Status | Evidence boundary |
 | --- | --- | --- |
-| Linux + OpenCode | Product: Node ^20.17.0 || >=22.9.0; source checks: Node 20.19.0 | Required Verify repository aggregates PR fast feedback and main package integration. Pull requests run policy, typecheck, build, and the two Vitest projects; main pushes additionally run Linux Node 20.19.0 source-built, packed-tarball, and fresh local-tarball installed checks. The dispatch-only support matrix retains exact product-floor Linux Node 20.17.0 and 22.9.0 imports plus latest Linux Node 20, 22, and 24 on demand. |
-| macOS + OpenCode | Manual limited smoke | The dispatch-only support matrix retains macOS Node 22 smoke only; this is not a promise of macOS Node 20/24 coverage. |
+| Linux CLI/package | Product: Node ^20.17.0 || >=22.9.0; source checks: Node 20.19.0 | Required Verify repository aggregates PR fast feedback and main package integration. Pull requests run policy, typecheck, build, and the two Vitest projects; main pushes additionally run Linux Node 20.19.0 source-built, packed-tarball, and fresh local-tarball installed checks. The dispatch-only support matrix retains exact product-floor Linux Node 20.17.0 and 22.9.0 imports plus latest Linux Node 20, 22, and 24 on demand. |
+| macOS CLI/package | Manual limited smoke | The dispatch-only support matrix retains macOS Node 22 smoke only; this is not a promise of macOS Node 20/24 coverage. |
 | Windows | Unverified / nonblocking | No Windows matrix job or support claim. Lock identity device/inode behavior and stale-lock/concurrency conclusions are not measured or verified. |
-| Codex adapter | Planned | No current Codex adapter or Codex product evidence; this is a planned adapter only. |
 
 Automatic CI boundary: Verify repository is the required PR/main aggregate. Pull requests require only the fast feedback lanes; main pushes also require Linux Node 20.19.0 package integration. The dispatch-only support matrix is deferred multi-runtime evidence, not a required PR/main gate. It is distinct from the canonical clean-CI builder's main-push signed evidence and the ordinary path-filtered diagnostic selftest.
 
@@ -439,8 +468,8 @@ Evidence answers one bounded question — *"What did this PH workflow observe fo
 this defined gate?"* — and nothing more. PH does **not** promise app-quality
 certification, token savings, Clean Code guarantees, broad AST/linter
 enforcement, a full TDD framework, closure guarantees, strong anti-forgery
-integrity before P3, or a complete workflow without OpenCode. The canonical list
-is in [MEASURED-CLAIMS](docs/MEASURED-CLAIMS.md).
+integrity before P3, or a proven live workflow route on every host. The
+canonical list is in [MEASURED-CLAIMS](docs/MEASURED-CLAIMS.md).
 
 > [!WARNING]
 > `ph bearshell` is **not a sandbox**. It limits runtime and output size, but commands still run on your machine with your permissions. See [SECURITY](SECURITY.md).
@@ -448,6 +477,7 @@ is in [MEASURED-CLAIMS](docs/MEASURED-CLAIMS.md).
 ## Docs
 
 - **New users** → [Start Here](docs/START-HERE.md) · [Quick Demo](docs/QUICK-DEMO.md) · [Measured Claims](docs/MEASURED-CLAIMS.md)
+- **Codex, Claude Code, OpenCode, or Antigravity** → [portable host adapter guide](docs/current/portable-host-adapters.md)
 - **Agent not following the rail?** → [Troubleshooting](docs/troubleshooting/README.md)
 - **Install & backend shape** → [MVP install guide](docs/current/java-backend-mvp-install-guide.md)
 - **Contributors** → [CONTRIBUTING](CONTRIBUTING.md) · [ROADMAP](ROADMAP.md) · [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md)

package/docs/START-HERE.md

@@ -12,14 +12,15 @@ A reading map for people seeing Persona Harness (PH) for the first time.
 ## I want to try it
 
 1. [QUICK-DEMO](QUICK-DEMO.md) — the fastest hands-on path.
-2. [README → Quick Start](../README.md#quick-start--javaspring-backend) — the
-   full workflow.
-3. For an existing Java/Spring/Gradle project, run `npx ph attach` to inspect
+2. [README → Quick Start](../README.md#quick-start) — the full workflow.
+3. [Portable host adapters](current/portable-host-adapters.md) — install the
+   shared-skill catalog for Codex, Claude Code, OpenCode, or Antigravity.
+4. For an existing Java/Spring/Gradle project, run `npx ph attach` to inspect
    the inferred draft, then `npx ph attach --yes` to accept it. Use
    `npx ph attach --repair --yes` only for a recognized weak Persona Harness
    installation, never a ready attachment; unrecognized or corrupt files are
    not overwritten.
-4. [Troubleshooting](troubleshooting/README.md) — if the agent implements
+5. [Troubleshooting](troubleshooting/README.md) — if the agent implements
    directly, ignores the rail, or skips tickets on an existing project.
 
 ## I want to contribute
@@ -38,6 +39,24 @@ A reading map for people seeing Persona Harness (PH) for the first time.
 
 ## Platform and host support
 
+### Portable host adapters
+
+`ph init` installs the canonical shared-skill catalog as manifest-owned regular
+files in every supported project layout. This makes the catalog discoverable; it
+does not establish that a running host session selected, loaded, or followed a
+skill.
+
+| Host | Generated path |
+| --- | --- |
+| Codex and Antigravity | `.agents/skills/persona-harness-<skill-id>/SKILL.md` |
+| Claude Code | `.claude/skills/persona-harness-claude-<skill-id>/SKILL.md` |
+| OpenCode | `.opencode/skills/persona-harness-opencode-<skill-id>/SKILL.md` |
+
+Read [Portable host adapters](current/portable-host-adapters.md) before
+customizing an adapter or expecting a package update to replace it. Context and
+legacy runtime injection remain default-off; Context delivery is still an
+OpenCode-specific optional boundary.
+
 ### Node runtime floor
 
 Sigstore-backed package verification requires Node.js ^20.17.0 || >=22.9.0;
@@ -52,12 +71,11 @@ diagnostics, not Finish authority. External assurance readiness is displayed
 through a separate read-only, non-consuming inspection; neither surface moves
 registry or trust state.
 
-| Surface | Status | Evidence boundary |
+| CLI/runtime surface | Status | Evidence boundary |
 | --- | --- | --- |
-| Linux + OpenCode | Product: Node ^20.17.0 || >=22.9.0; source checks: Node 20.19.0 | Required Verify repository aggregates PR fast feedback and main package integration. Pull requests run policy, typecheck, build, and the two Vitest projects; main pushes additionally run Linux Node 20.19.0 source-built, packed-tarball, and fresh local-tarball installed checks. The dispatch-only support matrix retains exact product-floor Linux Node 20.17.0 and 22.9.0 imports plus latest Linux Node 20, 22, and 24 on demand. |
-| macOS + OpenCode | Manual limited smoke | The dispatch-only support matrix retains macOS Node 22 smoke only; this is not a promise of macOS Node 20/24 coverage. |
+| Linux CLI/package | Product: Node ^20.17.0 || >=22.9.0; source checks: Node 20.19.0 | Required Verify repository aggregates PR fast feedback and main package integration. Pull requests run policy, typecheck, build, and the two Vitest projects; main pushes additionally run Linux Node 20.19.0 source-built, packed-tarball, and fresh local-tarball installed checks. The dispatch-only support matrix retains exact product-floor Linux Node 20.17.0 and 22.9.0 imports plus latest Linux Node 20, 22, and 24 on demand. |
+| macOS CLI/package | Manual limited smoke | The dispatch-only support matrix retains macOS Node 22 smoke only; this is not a promise of macOS Node 20/24 coverage. |
 | Windows | Unverified / nonblocking | No Windows matrix job or support claim. Lock identity device/inode behavior and stale-lock/concurrency conclusions are not measured or verified. |
-| Codex adapter | Planned | No current Codex adapter or Codex product evidence; this is a planned adapter only. |
 
 Automatic CI boundary: Verify repository is the required PR/main aggregate. Pull requests require only the fast feedback lanes; main pushes also require Linux Node 20.19.0 package integration. The dispatch-only support matrix is deferred multi-runtime evidence, not a required PR/main gate. It is distinct from the canonical clean-CI builder's main-push signed evidence and the ordinary path-filtered diagnostic selftest.
 

package/docs/current/README.md

@@ -19,8 +19,8 @@ history but do not become a current product or release claim.
 
 | I need to... | Start here |
 | --- | --- |
-| Install or understand the product | [Detailed usage](persona-harness-detailed-usage.md) and [workflow lifecycle](workflow-closure-state-machine-design.md) |
-| Use the portable shared-skill or product-discovery guidance | [Persona Shared Skills Core](persona-shared-skills-core.md) |
+| Install or understand the product | [Portable host adapters](portable-host-adapters.md) and [workflow lifecycle](workflow-closure-state-machine-design.md) |
+| Use the portable shared-skill or product-discovery guidance | [Persona Shared Skills Core](persona-shared-skills-core.md); use the portable-host guide above for host layouts. |
 | Maintain a local personalization profile | [Personalization Profile V1](personalization-profile-v1.md) |
 | Follow the Context Personalization program | [Context Personalization Program Status](context-program-status.md) |
 | Contribute to Context Personalization safely | [Context contributor map](context-contributor-map.json) |

package/docs/current/canonical-docs-index.md

@@ -12,7 +12,8 @@ Start with [Current Docs](README.md) unless you need a specific decision.
 | Workflow lifecycle projection | `docs/current/workflow-closure-state-machine-design.md` | The current fail-closed `workflow-lifecycle.1` state model. |
 | Workflow state concurrency | `docs/current/workflow-state-concurrency.md` | Writer ownership and safe state handling. |
 | Public product boundary | `docs/MEASURED-CLAIMS.md` | What Persona Harness may and may not claim. |
-| Install and usage | `docs/current/persona-harness-detailed-usage.md` | Detailed local install and maintenance-oriented usage. |
+| Install and usage | `docs/START-HERE.md` | Current first-run path for the workflow rail and host-neutral installation. |
+| Portable host adapters | `docs/current/portable-host-adapters.md` | Static adapter layouts, init ownership, update boundary, and host-evidence limits. |
 | Portable shared-skill and product-discovery contract | `docs/current/persona-shared-skills-core.md` | Catalog ownership, interview approval, capability-derived host assurance, explicit handoffs, and packaged surface. |
 | Personalization profile store | `docs/current/personalization-profile-v1.md` | Versioned local profile records, append-only lifecycle, privacy, and fail-closed storage. |
 | Context Personalization program | `docs/current/context-program-status.md` | Canonical P0 audit, isolated OpenCode delivery boundary, separation invariants, and claim status. |

package/docs/current/docs-inventory.md

@@ -115,6 +115,7 @@ Total indexed files: 342
 | `docs/current/npm-beta-publish-preparation.md` | current compatibility doc | - | Compatibility/current-era doc retained in place; migrate by summary and pointer before moving. |
 | `docs/current/omo-steal-measurement-report.md` | current or historical decision/status | - | Decision/status document; active only if named by docs/current/README.md, otherwise historical reference. |
 | `docs/current/persona-harness-detailed-usage.md` | operational stable | - | Stable non-versioned guide or index. |
+| `docs/current/portable-host-adapters.md` | current active pointer/status | - | Current portable static-adapter layouts, ownership, update, and host-evidence boundary. |
 | `docs/current/persona-harness-state-and-version.md` | current compatibility doc | - | Compatibility/current-era doc retained in place; migrate by summary and pointer before moving. |
 | `docs/current/persona-workflow-roles-v0.3.md` | current compatibility doc | - | Compatibility/current-era doc retained in place; migrate by summary and pointer before moving. |
 | `docs/current/p0-finish-next-action-acceptance-record.md` | current active pointer/status | - | P0-2 exact-main finish follow-up, report-transition, package evidence, and claim boundary record. |

package/docs/current/java-backend-mvp-install-guide.md

@@ -4,6 +4,11 @@
 
 Persona Harness의 현재 productized MVP는 Java/Spring backend Clean Code injection이다.
 
+이 문서는 선택적 OpenCode plugin 경로를 위한 Java/Spring guide다. `ph init`이
+Codex, Claude Code, OpenCode, Antigravity에 만드는 static shared-skill adapter의
+설치·소유권·갱신 경계는 [Portable Host Adapters](portable-host-adapters.md)를 먼저
+보세요. 이 문서의 OpenCode 예시는 다른 host가 지원되지 않는다는 뜻이 아니다.
+
 목표는 같은 요구사항에서 Gradle 기반, 계층 분리, DTO boundary, Repository boundary, Service orchestration-only backend product code shape가 더 균일하게 나오도록 Java target file에 rule context를 주입하는 것이다.
 
 frontend, infra, multi-domain shared skill은 후속 확장 후보이며 현재 release-facing MVP 범위가 아니다.

package/docs/current/persona-harness-detailed-usage.md

@@ -1,8 +1,14 @@
 # Persona Harness Detailed Usage Notes
 
-This document preserves the previous root README details after the public-facing README was simplified. Use this for local install, tarball verification, release readiness, plugin wiring, and development-oriented notes.
-
-The root [README.md](../../README.md) is now focused on first-time users.
+This document preserves previous root README details after the public-facing
+README was simplified. It includes historical OpenCode-only experiments and
+alpha-era setup instructions; do not use it as the current first-run or
+host-support guide.
+
+Start with the root [README.md](../../README.md),
+[Start Here](../START-HERE.md), and [Portable Host
+Adapters](portable-host-adapters.md). Use the retained notes below only when an
+older maintenance or experiment record is specifically relevant.
 
 ---
 

package/docs/current/persona-shared-skills-core.md

@@ -201,11 +201,15 @@ assumes every capability by default.
 
 The current OpenCode compact route uses one explicit bounded manifest and
 remains portable because its notice/session behavior is emulated and its
-generic pre-tool/completion enforcement capabilities are unavailable. This is
-not evidence that Claude Code, Codex, or Antigravity adapters are installed or
-live; host-specific generation and probing remain separate 0.9.0 work.
-The contract does not change selection, workflow authority, Context's explicit
-default-off boundary, or the legacy `runtimeInjection` default of `false`.
+generic pre-tool/completion enforcement capabilities are unavailable. The 0.9.0
+package materializes static adapters for Claude Code, Codex, and Antigravity as
+well as OpenCode; that package fact is not evidence that any host adapter is
+installed in a particular project or live in a particular session. Host-native
+selection and delivery remain separate observation boundaries. See [Portable
+Host Adapters](portable-host-adapters.md) for the generated layouts, ownership,
+and upgrade boundary. The contract does not change selection, workflow
+authority, Context's explicit default-off boundary, or the legacy
+`runtimeInjection` default of `false`.
 
 ## Package Boundary
 

package/docs/current/portable-host-adapters.md

@@ -0,0 +1,135 @@
+# Portable Host Adapters
+
+## Purpose
+
+Starting with Persona Harness 0.9.0, the canonical shared-skill catalog is
+discoverable in four agent hosts without a Persona-specific launch command:
+
+- Codex
+- Claude Code
+- OpenCode
+- Antigravity
+
+This is a **static adapter installation** boundary. It gives each host regular
+project-local `SKILL.md` files with the same catalog metadata and skill body. It
+does not prove that a running host session selected a skill, loaded it, or
+followed its guidance.
+
+## Install In Any Supported Host Project
+
+From the project root:
+
+```bash
+npm install -D persona-harness
+npx ph init
+npx ph doctor
+```
+
+`ph init` materializes the current canonical catalog in all of the following
+host discovery layouts:
+
+| Host | Generated adapter path |
+| --- | --- |
+| Codex and Antigravity | `.agents/skills/persona-harness-<skill-id>/SKILL.md` |
+| Claude Code | `.claude/skills/persona-harness-claude-<skill-id>/SKILL.md` |
+| OpenCode | `.opencode/skills/persona-harness-opencode-<skill-id>/SKILL.md` |
+
+Use your host's normal project-skill discovery mechanism after initialization.
+Persona Harness does not add a host-specific launch command or turn static
+discovery into a claim that the host selected a skill in the current session.
+
+## What Is Shared
+
+Every generated adapter points to the same Persona-owned catalog. It carries a
+short `name` and `description`, catalog identity, adapter layout, and package
+version. The catalog can advise one compact reference, such as
+`deep-interview`, `grill-me`, `programming`, `debug`, or `review`; discovery
+does not load every skill body.
+
+The adapter does not, merely by being discovered:
+
+- run shell commands;
+- create or advance workflow state;
+- use network, GitHub, evidence, or authority surfaces;
+- grant verification or Finish authority; or
+- enable Context or legacy runtime injection.
+
+The shared-skill routing and handoff contract is defined in
+[Persona Shared Skills Core](persona-shared-skills-core.md).
+
+## Ownership And Safe Re-runs
+
+The init manifest records every generated adapter path and digest. `ph init`
+may retain or refresh an unchanged Persona-owned adapter on a later run. It
+does not adopt neighboring user skills.
+
+Before any write, `ph init` checks each generated path as a no-follow regular
+file. It fails closed without a partial write when it encounters a user-owned,
+modified, missing-ownership, ambiguous, or symlinked target. In a clean
+checkout without an init manifest, only a byte-identical adapter can be
+re-owned.
+
+If an adapter is intentionally customized, preserve it as user-owned and do
+not expect `ph init` to replace it. Resolve the ownership collision deliberately
+instead of deleting or forcing files just to make initialization pass.
+
+## OpenCode Duplicate Prevention
+
+OpenCode can discover all three conventional project skill directories. The
+generated `.agents` and `.claude` adapters therefore declare
+`opencode/autoinvoke: "false"`; only the `.opencode` adapter declares
+`opencode/autoinvoke: "true"`. This leaves one native OpenCode candidate per
+canonical skill while preserving Codex, Antigravity, and Claude Code discovery.
+
+The existing optional OpenCode plugin registration remains separate from static
+adapter materialization. It may expose OpenCode-specific advisory behavior, but
+it does not change other hosts' semantics.
+
+## Context And Runtime Boundary
+
+`context.enabled` is explicit and default-off. Static portable adapters do not
+enable it. Context delivery is currently implemented only by the optional
+OpenCode adapter, and even there a local configuration or package check cannot
+prove a live session received a Context block.
+
+The legacy `runtimeInjection` setting also remains default-off. Portable
+adapters make skills discoverable; they do not silently enable runtime hooks,
+pre-tool enforcement, completion enforcement, session persistence, or automatic
+adapter updates on a host that lacks those controls.
+
+## Updating A Project
+
+Upgrade the package through your normal npm workflow, then re-run init from the
+same project root:
+
+```bash
+npm install -D persona-harness@latest
+npx ph init
+npx ph doctor
+```
+
+The later init can refresh only unchanged Persona-owned adapters. It will not
+overwrite custom files or follow symlinks. The optional `ph update enable`
+feature is an OpenCode plugin-pin update path; it does not automatically refresh
+the portable adapter layouts. A new host session is still required for a host to
+pick up any updated project-local skill files.
+
+## What `ph doctor` Can Verify
+
+`ph doctor` can report installed-package metadata, local integration files,
+ownership diagnostics, and configured Persona routes. It cannot inspect a live
+Codex, Claude Code, OpenCode, or Antigravity session. Treat host-native skill
+selection, activation notices, and delivery as host evidence, not as something
+proved by package installation alone.
+
+## Capability And Claim Boundary
+
+The versioned portable contract records per-host capability states as
+`supported`, `emulated`, or `unavailable`. It derives portable versus enforced
+assurance from that validated manifest rather than from a host name. A project
+that requires enforced assurance blocks if the host cannot supply the required
+control.
+
+This does not claim uniform runtime hooks or enforcement across hosts. It is a
+safe, host-neutral starting point for the same Persona skill catalog, while live
+host behavior remains a separately observable boundary.

package/docs/current/release/consumer-authority-current-acceptance.json

@@ -25,7 +25,7 @@
   "package": {
     "channel": "unpublished",
     "scope": "source-candidate",
-    "version": "0.9.0"
+    "version": "0.9.1"
   },
   "currentSourceCandidate": {
     "registryInstall": "requires-authorized-release-before-registry-install",

package/docs/current/release/v0.9.1-release-notes.md

@@ -0,0 +1,32 @@
+# v0.9.1 Release Notes
+
+## Portable Host Documentation
+
+This patch publishes the supported-host documentation for the portable skill
+adapters introduced in 0.9.0. The root README, Start Here guide, current
+documentation index, shared-skill package README, and Korean, Japanese, and
+Simplified Chinese entry pages now describe the same project-local adapter
+layouts for Codex, Claude Code, OpenCode, and Antigravity.
+
+The package also includes the canonical [Portable Host Adapters](../portable-host-adapters.md)
+guide so an installed consumer can inspect the generated paths and ownership
+rules without relying on repository-only documentation.
+
+## Boundaries Preserved
+
+- `ph init` materializes static, manifest-owned adapter files; installation does
+  not claim that a live host session selected or followed a skill.
+- Context and legacy runtime injection remain explicit and default-off. Current
+  Context delivery is still an optional OpenCode-specific runtime boundary.
+- `ph update enable` remains the optional OpenCode plugin-pin path. Updating
+  portable adapters requires a later `ph init` and only refreshes unchanged
+  Persona-owned files.
+- User-owned, modified, ambiguous, or symlinked adapter targets remain
+  fail-closed rather than being overwritten.
+
+## Verification
+
+The release path verifies documentation taxonomy and links, the public support
+matrix, package-file policy, TypeScript type safety, a canonical packed package,
+an isolated installed package with `sourceFallback=false`, protected CI, and
+registry provenance.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "persona-harness",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "private": false,
   "type": "module",
   "packageManager": "npm@10.8.2",
@@ -62,6 +62,7 @@
     "docs/current/v0.3.1-external-tester-feedback-template.md",
     "docs/current/v0.3.0-alpha-publish-readiness.md",
     "docs/current/persona-harness-detailed-usage.md",
+    "docs/current/portable-host-adapters.md",
     "docs/current/context-program-status.md",
     "docs/current/context-contributor-map.json",
     "docs/current/context-external-validation.md",

package/packages/shared-skills/README.md

@@ -37,6 +37,26 @@ metadata and Persona's optional automatic advisory-route configuration
 separately, and leaves adapter reachability, current host-native selection, and
 host route delivery as `UNOBSERVED` unless the host itself provides evidence.
 
+## Project-local host layouts
+
+`npx ph init` materializes this catalog as regular, manifest-owned adapters in
+each supported host layout:
+
+| Host | Adapter path |
+| --- | --- |
+| Codex and Antigravity | `.agents/skills/persona-harness-<skill-id>/SKILL.md` |
+| Claude Code | `.claude/skills/persona-harness-claude-<skill-id>/SKILL.md` |
+| OpenCode | `.opencode/skills/persona-harness-opencode-<skill-id>/SKILL.md` |
+
+Init may refresh only an unchanged Persona-owned adapter. User-owned, modified,
+or symlinked targets fail closed rather than being overwritten. The adapters
+make the catalog discoverable but do not enable Context, legacy runtime
+injection, workflow commands, shell, network, authority, or completion state.
+The generated OpenCode-native path is the only one eligible for OpenCode
+automatic discovery, preventing duplicate candidates from the other compatible
+layouts. See [Portable Host Adapters](../../docs/current/portable-host-adapters.md)
+for the full upgrade and host-evidence boundary.
+
 ## Portable Contract
 
 The root package exposes `persona-portable-skill-contract.1` through its

package/packages/shared-skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persona-harness/shared-skills",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "type": "module",
   "private": true,
   "description": "Persona-owned portable skill procedures and optional overlays",