chore: enforce Pi package catalog contract

.github/workflows/publish-npm.yml

@@ -1,6 +1,16 @@
 name: Publish npm package
 
 on:
+  pull_request:
+    branches: [main]
+    paths:
+      - package.json
+      - README.md
+      - extensions/**
+      - skills/**
+      - scripts/**
+      - docs/images/**
+      - .github/workflows/publish-npm.yml
   push:
     branches: [main]
     paths:
@@ -11,21 +21,39 @@ on:
       - LICENSE
       - extensions/**
       - skills/**
+      - scripts/**
+      - docs/images/**
       - .github/workflows/publish-npm.yml
   workflow_dispatch:
 
 concurrency:
-  group: npm-publish
-  cancel-in-progress: false
+  group: npm-publish-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 permissions:
   contents: read
-  id-token: write
 
 jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
+        with:
+          node-version: '22.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Pi package release gate
+        run: npm run verify:package
+
   publish:
-    if: github.repository == 'GroepOnline/pi-control'
+    needs: verify
+    if: github.repository == 'GroepOnline/pi-control' && github.event_name != 'pull_request'
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
     steps:
       - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7
         with:

ARCHITECTURE.md

@@ -1,23 +1,46 @@
 # Architecture
 
-`pi-control` is a thin in-process Pi extension. It does not run a daemon or hosted control plane.
+`pi-control` is a thin, in-process Pi extension. It runs no daemon, hosts no control plane, and keeps no second copy of Pi's state — every read and write goes through the live Pi host.
 
 ```text
 Pi host
-  -> extensions/pi-control/index.ts
-       -> commands/        operator slash workflows
-       -> tools.ts         structured agent tools
-       -> guardrails.ts    mutation / shell safety checks
-       -> Pi context APIs  session, model, tools, state
+  └─ extensions/pi-control/index.ts
+       ├─ commands/        operator slash workflows (/pi-demo, /pi-verify, /pi-qa)
+       ├─ tools.ts         five structured agent tools
+       ├─ guardrails.ts    lifecycle + tool-call safety hooks
+       └─ Pi context APIs  sessions, model, tools, state
+skills/pi-control/SKILL.md  packaged operating guidance
 ```
 
-## Ownership
+## Module ownership
 
-- `pi_session` inspects or changes the active Pi session.
-- `pi_model` controls the selected model and thinking level.
-- `pi_tool` inspects or replaces the active tool set.
-- `pi_state` stores small named snapshots used by control workflows.
-- `pi_verify` asserts observable runtime conditions after a change.
-- Guardrails intercept unsafe control/shell patterns before execution.
+| Module | Owns | Never does |
+| --- | --- | --- |
+| `index.ts` | Extension bootstrap; registers commands, tools, guardrails | Holds no state of its own |
+| `tools.ts` | `pi_session`, `pi_model`, `pi_tool`, `pi_state`, `pi_verify` | Bypasses Pi's own session/model/tool APIs |
+| `guardrails.ts` | Denies destructive shell patterns and gates unsafe mutations before execution | Intercepts anything outside control/shell patterns |
+| `commands/` | Operator workflows that compose the tools | Introduces separate state or side effects |
+| `skills/pi-control` | The capture → change → verify → report discipline for agents | Loads tools itself; Pi does that from the manifest |
 
-State that belongs to durable project work is intentionally outside this package; use `pi-missions`. Multi-agent execution belongs to `pi-agent-orchestrator`. Browser/terminal capture and evidence/showcase workflows belong to `pi-agent-control-extension`.
+## Data flow
+
+1. **Capture** — `pi_session inspect` / `pi_state save` record the current runtime state.
+2. **Change** — `pi_session fork|switch|compact`, `pi_model set|thinking`, `pi_tool set_active`, `pi_state restore` mutate the live process.
+3. **Verify** — `pi_verify session|model|tool|state` asserts observable expectations against the same process.
+4. **Report** — evidence comes from tool outputs and session dumps, not from a parallel model of the world.
+
+Guardrails sit in front of step 2: a denied mutation never reaches Pi's runtime.
+
+## Boundaries
+
+State that belongs to durable project work is intentionally outside this package — use [`@groeponline/pi-missions`](https://github.com/GroepOnline/pi-missions). Browser/terminal capture, QA evidence recipes, and showcase rendering belong to [`@groeponline/pi-agent-control-extension`](https://github.com/GroepOnline/pi-agent-control-extension). Operator cockpit surfaces (status bar, queue, Skill Studio) belong to [`@groeponline/pi-wishcraft`](https://github.com/GroepOnline/pi-wishcraft).
+
+## Packaging
+
+The npm package carries the extension entrypoint, the skill, and the hero assets declared in `package.json` (`pi.extensions`, `pi.skills`, `pi.image`). The [`verify:pi-package`](scripts/verify-pi-package-contract.mjs) gate validates the manifest, resource existence, public metadata, gallery preview format, Pi core peer-dependency rules, and the final packed tarball on every PR and before every publish.
+
+## Testing
+
+- `scripts/package-contract-runtime.test.mjs` — contract-parser regressions
+- `extensions/pi-control/tests/` — extension unit tests (`npm test --prefix extensions/pi-control`)
+- CI (`publish-npm.yml`) runs both plus the full gate, then publishes with provenance when the version is new

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [Unreleased]
+
+## 0.1.3
+
+- Rewrite README, architecture, and packaged skill documentation; align the skill with the current tool surface (`pi_state restore`, `pi_verify session|model|tool|state`) and make all operator documentation English-only for the Pi catalog.
+- Sharpen npm/Pi catalog metadata (description, keywords) for discoverability on pi.dev and npm search.
+
 ## 0.1.2 - 2026-08-30
 
 - Document concrete structured tool calls and package ownership boundaries.
@@ -9,3 +16,7 @@
 ## 0.1.1
 
 - Public npm/Pi package metadata, MIT licensing, clean install, and package-content verification.
+
+## 0.1.0
+
+- Initial release: session, model, tool, and state tools; `/pi-demo`, `/pi-verify`, `/pi-qa` commands; guardrails; packaged `pi-control` skill.