Align documentation with public npm

.changeset/readme-trigger-skill.md

@@ -2,5 +2,5 @@
 "@operatorstack/yield": patch
 ---
 
-Explain how to run a registered skill from a new coding-agent session and fix
-the README logo on npm.
+Explain how to register and run a skill, fix the README logo on npm, and point
+readers to current public documentation.

README.md

@@ -20,7 +20,7 @@
 
 <p align="center">
   <a href="https://yield.operatorstack.systems/">Website</a> ·
-  <a href="docs/README.md">Documentation</a> ·
+  <a href="https://yield.operatorstack.systems/docs/">Documentation</a> ·
   <a href="https://www.npmjs.com/package/@operatorstack/yield">npm</a> ·
   <a href="https://github.com/operatorstack/yield">GitHub</a>
 </p>
@@ -247,6 +247,7 @@ loop, multi-agent orchestrator, or security sandbox.
 
 ## Documentation and development
 
+- [Read the public documentation](https://yield.operatorstack.systems/docs/)
 - [What a skill workflow is](docs/skill-workflows.md)
 - [Ten-minute TypeScript quickstart](docs/quickstart.md)
 - [Working examples in all four languages](docs/examples.md)
@@ -267,4 +268,5 @@ updates, database migration, security audit, and package release.
 
 ---
 
-Yield is MIT licensed. This repository is its canonical source.
+Yield is MIT licensed. This repository contains its canonical source and
+versioned technical documentation.

docs/README.md

@@ -1,14 +1,20 @@
 # Yield documentation
 
-You already know the skill workflow. You may be repeating it in a prompt:
+Move repeatable coding-agent instructions from words into code.
+
+The [public documentation](https://yield.operatorstack.systems/docs/) is the
+best place to start. This directory contains the versioned technical source
+that stays with each Yield revision.
+
+You may already be repeating a workflow in a prompt:
 
 > Run the checks. Review the diff. Stop if anything critical remains. Ask me
 > before publishing. If the session ends, start again without losing our place.
 
 Yield lets you keep the useful words and put the repeatable flow in normal
-code. The coding agent still investigates, reviews, edits, and explains. Your program
-decides which operation comes next, what evidence must exist, and when the run
-is finished.
+code. The coding agent still investigates, reviews, edits, and explains. Your
+program decides which operation comes next, what evidence must exist, and when
+the run is finished.
 
 A **skill workflow** is a portable, executable process that combines agent
 skills with deterministic code, state, and verification. The canonical
@@ -17,19 +23,21 @@ and start it.
 
 ## Start here
 
-1. [Understand skill workflows](skill-workflows.md) — the canonical workflow,
+1. [Read the public guide](https://yield.operatorstack.systems/docs/) — the
+   quickest path from installation to a running workflow.
+2. [Understand skill workflows](skill-workflows.md) — the canonical workflow,
    generated adapter, and execution boundary.
-2. [Build and run your first skill workflow](quickstart.md) — a TypeScript
+3. [Build and run your first skill workflow](quickstart.md) — a TypeScript
    workflow you can test in about ten minutes.
-3. [Register it with your coding agents](agent-setup.md) — keep one workflow
+4. [Register it with your coding agents](agent-setup.md) — keep one workflow
    and generate the small discovery adapters each agent needs.
-4. [Learn the primitives](primitives/README.md) — commands, model work, human
+5. [Learn the primitives](primitives/README.md) — commands, model work, human
    input, gates, and honest outcomes.
-5. [Follow a complete tutorial](tutorials/README.md) — review, approval,
+6. [Follow a complete tutorial](tutorials/README.md) — review, approval,
    environment repair, bounded debugging, and migration.
-6. [Browse the examples](examples.md) — working skill workflows in Go,
+7. [Browse the examples](examples.md) — working skill workflows in Go,
    TypeScript, Python, and Rust.
-7. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's
+8. [Convert an existing prose skill](convert-existing-skill.md) — use Yield's
    verified converter after you understand one ordinary workflow.
 
 ## The split to remember
@@ -52,7 +60,6 @@ response and resumes from the next unanswered operation.
 - [Skill workflow concepts](skill-workflows.md)
 - [CLI commands](reference/cli.md)
 - [Coding-agent registration](agent-setup.md)
-- [Agent Plugins and Yield](agent-plugins.md)
 - [Run, pause, resume, and replay](reference/execution-model.md)
 - [The four SDKs](reference/sdk-parity.md)
 - [Guarantees and limits](reference/guarantees.md)

docs/agent-setup.md

@@ -51,6 +51,24 @@ workflow. Yield refuses to overwrite a user-owned skill with the
 same name. Names must also be unique across languages because coding agents use
 one project-level skill namespace.
 
+## Run the registered skill
+
+Start a new coding-agent session after registration. Where slash skills are
+supported, run the generated skill by name:
+
+```text
+/review
+```
+
+Otherwise, ask the agent to use it:
+
+```text
+Use the review skill to check the current branch.
+```
+
+The host owns how the request is presented. The generated adapter starts the
+canonical workflow under `skills/review`; it does not contain a second copy.
+
 ## Copy this to your agent
 
 Replace the bracketed values, then paste this into the coding agent already

docs/quickstart.md

@@ -12,8 +12,7 @@ You need Node.js 24 or newer.
 mkdir yield-example
 cd yield-example
 npm init -y
-npm install --save-exact @operatorstack/yield@0.1.29 \
-  --registry=https://get.operatorstack.systems/npm/
+npm install --save-exact @operatorstack/yield
 npm exec -- yskill --version
 ```
 
@@ -125,16 +124,31 @@ Yield keeps one canonical skill workflow and writes only generated adapters:
 .claude/skills/review/SKILL.md   # Claude Code
 ```
 
-Start a new agent session after registration, then invoke `/review` or ask for
-the task described by the skill.
-
 Check the generated adapters:
 
 ```bash
 npm exec -- yskill doctor skills/review \
   --agent cursor,codex,claude-code
 ```
 
+## 6. Run the skill
+
+Start a new coding-agent session so it discovers the generated adapter. Where
+slash skills are supported, run:
+
+```text
+/review
+```
+
+Otherwise, ask the agent in plain language:
+
+```text
+Use the review skill to check the current branch.
+```
+
+The agent starts the canonical workflow in `skills/review` and follows each
+operation until the run completes, blocks, or is refused.
+
 ## Run an existing workflow
 
 Initialization is only for creating or wrapping a workflow. For an existing

scripts/readme.test.mjs

@@ -106,3 +106,20 @@ test("README uses the edge-cropped Yield mark", async () => {
   assert.match(mark, /viewBox="0 0 60 60"/);
   assert.match(mark, /<rect x="1" y="1" width="58" height="58"/);
 });
+
+test("README and quickstart use the public documentation and npm registry", async () => {
+  const [readme, docsIndex, quickstart, agentSetup] = await Promise.all([
+    text("README.md"),
+    text("docs/README.md"),
+    text("docs/quickstart.md"),
+    text("docs/agent-setup.md"),
+  ]);
+
+  assert.match(readme, /href="https:\/\/yield\.operatorstack\.systems\/docs\/">Documentation<\/a>/);
+  assert.match(docsIndex, /\[public documentation\]\(https:\/\/yield\.operatorstack\.systems\/docs\/\)/);
+  assert.match(quickstart, /npm install --save-exact @operatorstack\/yield/);
+  assert.doesNotMatch(quickstart, /get\.operatorstack\.systems\/npm|@operatorstack\/yield@0\./);
+  assert.match(quickstart, /^## 6\. Run the skill$/m);
+  assert.match(quickstart, /^\/review$/m);
+  assert.match(agentSetup, /^## Run the registered skill$/m);
+});