@pieai/pro-gov 0.3.3 → 0.3.5

package/README.md

@@ -1,19 +1,31 @@
 # @pieai/pro-gov
 
-Project-level distribution kit for Project Governance System.
+`@pieai/pro-gov` is the project-level setup kit for
+[Project Governance System](https://github.com/PieAIStudio/ProjectGovernanceSystem).
+It helps AI-assisted projects stay understandable after many plans, documents,
+tools, and AI sessions have accumulated.
 
-`@pieai/doc-gov` remains the validator package. `@pieai/pro-gov` ships reusable
-project-governance assets and a conservative project-level CLI. It is the
-package that answers: "What starter/profile material does this project need,
-and what would change if we adopted it?"
+Think of Project Governance System as a librarian, traffic desk, and inspection
+station:
+
+- `pro-gov` shows which reusable project-governance parts are present or missing;
+- `@pieai/doc-gov` checks documents, routing, links, hooks, and CI;
+- Superpowers may provide the engineering process;
+- Ponytail may provide an optional simplicity review.
+
+The current `pro-gov` release is conservative by design. Public init and sync
+commands inspect and compare; they do not silently overwrite another project's
+router or local truth.
 
 ## Install
 
+Requires Node.js `22.12.0` or newer.
+
 ```bash
 pnpm add -D @pieai/pro-gov @pieai/doc-gov
 ```
 
-Add scripts in the target project:
+Optional project scripts:
 
 ```json
 {
@@ -24,24 +36,77 @@ Add scripts in the target project:
 }
 ```
 
-## Commands
+## Public Commands
 
 ```bash
 pro-gov assets list
+pro-gov assets discover --target .
+pro-gov assets recommend --target .
+pro-gov lens inspect --target .
+pro-gov lens report --target . --out .pro-gov/lens-report.md
 pro-gov init --profile engineering-runtime --dry-run
 pro-gov init --profile doc-only --dry-run
 pro-gov sync --check
 pro-gov doctor
 ```
 
-The first release is read-only by default. It reports what would change before
-any future write path is added.
+What these commands do:
+
+| Command group | Purpose | Writes project files? |
+| --- | --- | --- |
+| `assets list` | Shows packaged assets and public registry metadata. | No |
+| `assets discover` | Detects local project signals. | No |
+| `assets recommend` | Suggests relevant asset bundles with reasons. | No |
+| `lens inspect` | Produces ProjectLens-style local evidence. | No |
+| `lens report` | Writes the requested report file. | Only the explicit output |
+| `init --dry-run` | Shows starter/profile files that would be needed. | No |
+| `sync --check` | Compares local starter files with packaged assets. | No |
+| `doctor` | Checks required packaged assets and whether `doc-gov` is available. | No |
+
+## Full Checkout Commands
+
+A full Project Governance System checkout may also manage Yuanfei's local
+agent-asset registry through reviewed plans:
+
+```bash
+pro-gov assets plan --bundle base-governance --target . --out .pro-gov/asset-plan.json
+pro-gov assets apply --plan .pro-gov/asset-plan.json
+pro-gov assets check --target .
+pro-gov assets npx update --plan
+```
+
+The plan is the safety gate. `apply` may update managed targets described by the
+plan; it must not overwrite an unrelated unmanaged file.
+
+These checkout-only workflows depend on the upstream `agent-assets/` registry.
+The public npm package intentionally excludes private and mirrored third-party
+skill bodies.
 
 ## Package Boundary
 
-- `pro-gov` lists and compares starter/profile/integration assets.
-- `doc-gov` validates governed Markdown, router integrity, manifest freshness,
-  links, local hooks, and CI wiring.
-- Project-local product truth stays in the target project.
-- Write-mode install or upgrade behavior is intentionally not enabled in the
-  first release.
+- `pro-gov` distributes starter, profile, integration, and adoption assets.
+- `pro-gov assets discover|recommend` provides read-only project evidence and
+  deterministic recommendations.
+- `pro-gov assets plan|apply|check` manages local assets only from an explicit,
+  reviewable plan in a full upstream checkout.
+- `pro-gov lens inspect|report` provides read-only inspection and an explicit
+  report output.
+- `doc-gov` remains the document, router, manifest, link, hook, CI, and migration
+  validator.
+- Product truth stays in the target project.
+- Write-mode `pro-gov init --apply` is not enabled in this release.
+- Superpowers and Ponytail are external tools, not bundled runtime dependencies.
+
+## Recommended Companion Tools
+
+Superpowers is recommended for engineering/runtime projects that need
+brainstorming, plans, TDD, debugging, verification, and worktree discipline.
+
+Ponytail can be installed as an optional complexity adviser. Keep its global mode
+`off`; test `lite` in one isolated task before considering a stronger mode.
+Ponytail must not remove requested scope, tests, safety, accessibility, or proof.
+
+Read the
+[full project introduction](https://github.com/PieAIStudio/ProjectGovernanceSystem#readme)
+for beginner examples, profiles, adoption guidance, and exact integration
+boundaries.

package/assets/docs/reference/adoption/adoption-playbook.md

@@ -6,7 +6,7 @@ status: stable
 canonical: true
 owner: human
 created: 2026-05-06
-last_reviewed: 2026-06-13
+last_reviewed: 2026-06-15
 domain: adoption
 tags:
   - adoption
@@ -22,16 +22,22 @@ related:
 
 Use this when a project wants to migrate into the Project Governance System.
 
+Before choosing external AI workflow tools, read
+`docs/reference/adoption/recommended-agent-tooling.md`. It explains which PGS
+packages are required, when Superpowers is recommended, and why Ponytail should
+remain globally `off` until it is tested in an isolated task.
+
 ## The Short Version
 
 1. Pick one profile.
 2. Inventory the project's current docs/rules.
 3. Install the governance packages.
-4. Add starter `docs/governance/` and `docs/policy/` files.
-5. Add the selected `docs/governance/agents-routing/` profile rule.
-6. Move current truth into the governed layers.
-7. Archive or delete old systems.
-8. Run validation.
+4. Run project and agent-asset discovery.
+5. Add starter `docs/governance/` and `docs/policy/` files.
+6. Add the selected `docs/governance/agents-routing/` profile rule.
+7. Move current truth into the governed layers.
+8. Archive or delete old systems.
+9. Run validation.
 
 Do not migrate by slowly adding random files. Migrate by making one clear current work surface.
 
@@ -66,6 +72,11 @@ Current package-based method:
   the starter files that would be installed
 - run `pro-gov sync --check` to compare reusable starter files without changing
   the project
+- run `pro-gov assets discover --target <path>` and
+  `pro-gov assets recommend --target <path>` to collect local project signals
+  and suggested agent-asset bundles without changing the project
+- run `pro-gov lens inspect --target <path>` when the project needs a
+  ProjectLens-style local evidence packet
 - run `doc-gov migrate --profile <engineering-runtime|doc-only> --check` before
   changing files so profile mismatches fail early
 - run `doc-gov router-check` after the sync so stale router/profile paths fail
@@ -97,6 +108,27 @@ the private workspace package name is `pro-gov`. Target projects should use
 for public links, and refer to the source as the Project Governance System
 upstream repository.
 
+### Optional: Managed Agent Assets
+
+Agent assets are skills, rules, and commands exposed to AI hosts. They are not
+the same as governed project docs.
+
+Use this flow only from a full Project Governance System checkout that contains
+`agent-assets/`; the public npm package excludes Yuanfei's private and
+third-party skill bodies by design:
+
+```bash
+pro-gov assets discover --target /path/to/project --json
+pro-gov assets recommend --target /path/to/project --json
+pro-gov assets plan --target /path/to/project --bundle base-governance --host codex --out /tmp/pro-gov-asset-plan.json
+pro-gov assets apply --plan /tmp/pro-gov-asset-plan.json
+pro-gov assets check --target /path/to/project --json
+```
+
+The plan file is the safety gate. Review it before applying. It creates managed
+symlinks and `.pro-gov/assets.lock.json`; it should not overwrite unmanaged
+project files.
+
 ## Step 4: Add Starter Structure
 
 Use `starter/` as the reference, but keep local facts local.
@@ -145,6 +177,10 @@ Add:
 
 Do not add Superpowers TDD or Directed Development by default.
 
+Ponytail is also optional. If it is installed, keep its global mode `off` and
+activate it only for a bounded task or review after reading
+`integrations/ponytail.md`.
+
 ## Step 6: Create Current Work
 
 Create or update:

package/assets/docs/reference/adoption/downstream-project-registry.md

@@ -6,7 +6,7 @@ status: active
 canonical: true
 owner: human
 created: 2026-06-09
-last_reviewed: 2026-06-13
+last_reviewed: 2026-06-14
 domain: adoption
 tags:
   - downstream
@@ -30,9 +30,12 @@ downstream projects.
 ## Registry Rules
 
 - Update this file when a project adopts, leaves, renames, or changes profile.
+- Keep only projects that currently exist and are expected to receive future
+  governance updates. Remove deleted or superseded projects instead of keeping
+  stale health rows.
 - Treat package versions as the versions installed in the downstream project's
-  `package.json`. Existing rows may list only `doc-gov` until that project is
-  intentionally synced to `pro-gov`.
+  `package.json`. Record both packages when the project has completed
+  package-based adoption.
 - Treat health as a snapshot. A project can be on the latest version but still
   have local working-tree cleanup in progress.
 - Do not add a project-specific profile here unless at least two projects need
@@ -44,18 +47,21 @@ downstream projects.
 
 ## Current Downstream Projects
 
-Checked on 2026-06-09.
+The current downstream set was checked on 2026-06-14.
 
-| Project | Local path | Profile | Installed doc-gov | Health snapshot | Notes |
-| --- | --- | --- | --- | --- | --- |
-| Non-Heroes | `/Users/yuanfei/PieAI/Non-Heroes` | `engineering-runtime` | `0.3.2` | Partial | Package and router are current; local doc migration work is in progress, so `doctor` currently fails on moved/archive reference docs until that project is cleaned up. |
-| Show | `/Users/yuanfei/PieAI/Show` | `engineering-runtime` | `0.3.2` | Healthy | `router-check` and `doctor` pass. |
-| PieFlow | `/Users/yuanfei/PieAI/PieFlow` | `engineering-runtime` | `0.3.2` | Healthy | `router-check` and `doctor` pass. |
-| story-creator | `/Users/yuanfei/PieAI/_NovelFrameworks/story-creator` | `engineering-runtime` | `0.3.2` | Healthy | Uses engineering routing because the repository contains a TypeScript CLI, tests, hooks, gates, and writing-system runtime. |
-| PieAIStudio-Site | `/Users/yuanfei/PieAI/PieAIStudio-Site` | `engineering-runtime` | `0.3.2` | Healthy | `router-check` and `doctor` pass. |
-| PieHQ | `/Users/yuanfei/PieAI/PieHQ` | `doc-only` | `0.3.2` | Healthy | `router-check` and `doctor` pass; unrelated FounderLogs work is present locally. |
-| PieIP | `/Users/yuanfei/PieAI/PieIP` | `doc-only` | `0.3.2` | Healthy | `router-check` and `doctor` pass. |
-| ProjectLens | `/Users/yuanfei/PieAI/ProjectLens` | `doc-only` | `0.3.2` | Healthy | `router-check` and `doctor` pass; ProjectLens is a project-level audit workspace, not a runtime product. |
+| Project | Local path | Profile | Installed doc-gov | Installed pro-gov | Health snapshot | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| Anvil | `/Users/yuanfei/PieAI/Anvil` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. Existing unrelated local writing work was preserved. |
+| Collapse | `/Users/yuanfei/PieAI/Collapse` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | Adopted the thin placeholder-phase runtime profile. `docs:check` and the production build pass. |
+| Non-Heroes | `/Users/yuanfei/PieAI/Non-Heroes` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. |
+| PieAIStudio-Site | `/Users/yuanfei/PieAI/PieAIStudio-Site` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. Existing unrelated local skill links were preserved. |
+| PieHQ | `/Users/yuanfei/PieAI/PieHQ` | `doc-only` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. |
+| Sea | `/Users/yuanfei/PieAI/Sea` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings across the large governed-doc set. |
+| Show | `/Users/yuanfei/PieAI/Show` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. |
+| SupaLuv | `/Users/yuanfei/PieAI/SupaLuv` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | Migrated from the vendored `doc-gov@0.2.0` copy. `docs:check` and `cloud:check` pass; unrelated local content work was preserved. |
+| YaZu | `/Users/yuanfei/PieAI/YaZu` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. |
+| TuringPact | `/Users/yuanfei/PieAI/TuringPact` | `engineering-runtime` | `0.3.3` | `0.3.3` | Healthy | Migrated the legacy `Docs/` system into current, completed, and archive layers. `docs:check` and `verify:web` pass. |
+| ProjectLens | `/Users/yuanfei/PieAI/ProjectLens` | `doc-only` | `0.3.3` | `0.3.3` | Healthy | `docs:check` passes with 0 warnings. ProjectLens is a project-level audit workspace, not a runtime product. |
 
 ## Representative Examples
 
@@ -63,9 +69,6 @@ The `examples/` directory is not the full registry. It contains representative
 case studies:
 
 - `examples/non-heroes/example.md` for an engineering-runtime product.
-- `examples/pieflow/example.md` for a complex app/runtime product.
-- `examples/pieip/example.md` for a doc-only AI media / asset-governance
-  project.
 
 Add a new example only when a project teaches a reusable adoption pattern that
 the existing examples do not cover.
@@ -74,5 +77,9 @@ the existing examples do not cover.
 
 - `Supa` is no longer tracked here because that project was renamed/replaced by
   `Non-Heroes`.
+- `story-creator` is no longer tracked because the repository was renamed and
+  replaced by `Anvil`.
+- `PieFlow` and `PieIP` were removed from the current registry on 2026-06-14
+  because those projects were deleted.
 - GitNexus is intentionally absent. It has been removed from the central system
   and should not be reintroduced through downstream policy links.

package/assets/docs/reference/adoption/project-relationship.md

@@ -32,8 +32,8 @@ The central repo owns the **engine**. Each project owns its **local product cont
 | --- | --- |
 | Status lifecycle, document types, SSOT, agents routing, CLI checks, templates | Project Governance System upstream repository |
 | Non-Heroes product plans, runtime canon, product rules | Non-Heroes |
-| PieFlow product truth, connector rules, browser lanes | PieFlow |
-| PieIP character/script/asset governance | PieIP |
+| TuringPact product truth, game runtime, commercial Gates | TuringPact |
+| ProjectLens audit evidence and observer workflow | ProjectLens |
 | Current downstream adoption list and health snapshot | `docs/reference/adoption/downstream-project-registry.md` |
 
 ## Naming And Checkout Paths
@@ -62,10 +62,10 @@ Not yet automatically.
 Known downstream projects are listed in
 `docs/reference/adoption/downstream-project-registry.md`.
 
-Originally Non-Heroes, PieFlow, and PieIP had local working copies because the
-system was born inside active projects. This central repo is now the upstream
-source, and downstream projects should use `@pieai/doc-gov`, `@pieai/pro-gov`,
-and their selected profile instead of keeping private CLI or starter copies.
+Early downstream projects had local working copies because the system was born
+inside active projects. This central repo is now the upstream source, and
+downstream projects should use `@pieai/doc-gov`, `@pieai/pro-gov`, and their
+selected profile instead of keeping private CLI or starter copies.
 
 ## Why Not Auto-Symlink Everything?
 
@@ -79,7 +79,8 @@ The old `governance/` folder mixed both kinds. The clearer split is:
 - `docs/governance/` contains doc-system rules, SSOT, agents-routing, document types, templates, and manifest.
 - `docs/policy/` contains project-local AI development policy, lane wording, proof commands, and truth hierarchy.
 
-Symlinking or copying the whole policy layer would be wrong because Non-Heroes and PieFlow need different local lane profiles. The safe rule:
+Symlinking or copying the whole policy layer would be wrong because different
+projects need different local lane profiles. The safe rule:
 
 - shared rules may be symlinked
 - doc-gov core should become the installed validator package
@@ -104,7 +105,7 @@ Example:
 - The generic fix is a `completed` lifecycle state.
 - Therefore `completed` belongs in this repo's doc-gov core.
 
-## How PieFlow And PieIP Upgrade
+## How Downstream Projects Upgrade
 
 Use an explicit migration task:
 

package/assets/docs/reference/adoption/public-release-checklist.md

@@ -6,7 +6,7 @@ status: stable
 canonical: true
 owner: human
 created: 2026-06-04
-last_reviewed: 2026-06-13
+last_reviewed: 2026-06-21
 domain: adoption
 tags:
   - release
@@ -69,28 +69,55 @@ Before publishing:
 - package dry-runs show only intended files
 - publish `@pieai/doc-gov` before `@pieai/pro-gov` when both package versions
   are new, because `pro-gov` depends on the matching validator release
-- maintainer is authenticated to npm
+- npm Trusted Publisher is configured for both packages
 - registry is the official npm registry, not a mirror
 - scoped publish uses public access
 
-Recommended commands:
+Recommended local verification:
 
 ```bash
-npm whoami --registry https://registry.npmjs.org/
-
 pnpm --filter @pieai/doc-gov pack --dry-run
 pnpm --filter @pieai/pro-gov pack --dry-run
+```
 
-pnpm --filter @pieai/doc-gov publish --access public --registry https://registry.npmjs.org/
-npm view @pieai/doc-gov version --registry https://registry.npmjs.org/
+Recommended publish command:
 
-pnpm --filter @pieai/pro-gov publish --access public --registry https://registry.npmjs.org/
-npm view @pieai/pro-gov version --registry https://registry.npmjs.org/
+```bash
+gh workflow run npm-publish.yml --ref main
 ```
 
 Important: do not claim an npm package is live until its `npm view <package>
 version` command resolves from the public registry.
 
+## Trusted Publishing Setup
+
+npm publishing should use Trusted Publishing through GitHub Actions. This is the
+smooth path: GitHub Actions proves to npm that a specific workflow in this
+repository is publishing the package, so maintainers do not need to pass a
+long-lived npm token around.
+
+Set this once for each package on npmjs.com:
+
+1. Open the package settings for `@pieai/doc-gov`.
+2. Add a Trusted Publisher for GitHub Actions:
+   - owner: `PieAIStudio`
+   - repository: `ProjectGovernanceSystem`
+   - workflow file: `npm-publish.yml`
+   - allowed action: `npm publish`
+3. Repeat the same setup for `@pieai/pro-gov`.
+4. Keep the workflow as manual `workflow_dispatch` until several releases have
+   succeeded.
+
+The workflow must keep:
+
+- `permissions.id-token: write`
+- a GitHub-hosted runner
+- npm CLI `11.5.1` or newer
+- package `repository` fields that match the public GitHub repository
+- `pnpm pack` before publish, so workspace dependencies are converted in the
+  tarball
+- `npm publish <tarball> --provenance --access public`
+
 ## After Release
 
 After GitHub and npm are live:
@@ -101,23 +128,3 @@ After GitHub and npm are live:
 - update downstream projects only through an explicit sync task
 - update public website copy from the current README and this checklist, not
   from stale chat history
-
-## Future: Trusted Publishing
-
-The first release may be published from a logged-in maintainer machine. Future
-releases should move to npm Trusted Publishing through GitHub Actions.
-
-Recommended future setup:
-
-1. On npmjs.com, open the package settings for `@pieai/doc-gov` and
-   `@pieai/pro-gov`.
-2. Add a Trusted Publisher for GitHub Actions to each package:
-   - owner: `PieAIStudio`
-   - repository: `ProjectGovernanceSystem` (GitHub slug)
-   - workflow file: `npm-publish.yml`
-3. Keep the workflow as manual `workflow_dispatch` until the first trusted
-   publishing run succeeds.
-4. After that, optionally add a release-tag trigger such as `v0.3.1`.
-
-Trusted Publishing gives npm a verifiable GitHub build origin and avoids
-long-lived npm tokens.

package/assets/docs/reference/adoption/recommended-agent-tooling.md

@@ -0,0 +1,106 @@
+---
+id: REF-RECOMMENDED-AGENT-TOOLING
+title: Recommended Agent Tooling
+type: reference
+status: stable
+canonical: true
+owner: human
+created: 2026-06-21
+last_reviewed: 2026-06-21
+domain: adoption
+tags:
+  - adoption
+  - tooling
+  - superpowers
+  - ponytail
+pinned: false
+related:
+  - REF-ADOPTION-PLAYBOOK
+  - POLICY-DESIGN-PRINCIPLES
+  - POLICY-SYNC-STRATEGY
+---
+
+# Recommended Agent Tooling
+
+This page separates what a project needs from what may help it.
+
+## The Beginner Version
+
+Imagine a school workshop:
+
+- PGS labels the shelves, routes each job, and checks that the record is complete.
+- Superpowers gives the class a reliable build-and-test routine.
+- Ponytail is the adviser who asks, "Can we make this with fewer unnecessary
+  parts?"
+
+Installing every tool does not mean every tool should run all the time.
+
+## Recommendation Table
+
+| Tool | Recommendation | Best fit | Default behavior |
+| --- | --- | --- | --- |
+| `@pieai/pro-gov` | Required for package-based PGS adoption | Projects adopting PGS starter/profile assets | Use its read-only discovery, init, sync, doctor, and Lens commands. |
+| `@pieai/doc-gov` | Required for package-based PGS adoption | All governed PGS projects | Run document, router, manifest, link, hook, and CI checks. |
+| Superpowers | Recommended for engineering/runtime projects | Apps, games, services, browser products, and other code-heavy work | Use the matching workflow when the selected PGS lane requires it. |
+| Ponytail | Recommended as an installed, optional adviser | Projects that need help resisting unnecessary complexity | Keep the global mode `off`; activate it explicitly for a bounded task or review. |
+
+## Superpowers
+
+Superpowers owns engineering workflow discipline:
+
+- brainstorming before creative implementation;
+- implementation plans;
+- test-driven development;
+- systematic debugging;
+- verification before completion;
+- isolated worktree usage.
+
+PGS routes the task first. Superpowers then runs inside the selected lane.
+
+Engineering/runtime projects usually benefit from Superpowers. Doc-only
+projects should not inherit the full engineering ceremony unless their current
+task actually involves runtime or code behavior.
+
+Read `integrations/superpowers.md` for the exact boundary.
+
+## Ponytail
+
+Ponytail advises the AI to prefer smaller, less speculative solutions. That can
+reduce unnecessary code, files, dependencies, and abstractions.
+
+Keep its global mode `off`. When a low-risk task needs a simplicity comparison,
+test `lite` in an isolated session first. Use `full` only as an optional stress
+test after checking that requirements, tests, verification, security,
+accessibility, and durable evidence remain intact.
+
+Ponytail is not a replacement for PGS or Superpowers. Shorter work is valuable
+only when it is still the complete, proven work the project asked for.
+
+Read `integrations/ponytail.md` for the mode policy and comparison protocol.
+
+## A Practical Default
+
+For an engineering/runtime project:
+
+```text
+install PGS packages
+-> keep Superpowers available for engineering workflows
+-> install Ponytail but keep global mode off
+-> activate Ponytail only when a bounded simplicity review would help
+```
+
+For a doc-only project:
+
+```text
+install PGS packages
+-> use doc-only routing and evidence rules
+-> add engineering workflow tools only for a real engineering task
+-> keep Ponytail optional and off by default
+```
+
+## What PGS Does Not Do
+
+PGS does not automatically install, enable, update, or remove these external
+plugins in another person's AI host. It documents the recommended boundary and
+lets each project or user adopt tools deliberately.
+

package/assets/docs/reference/adoption/site-publication-brief.md

@@ -25,19 +25,20 @@ System as a public project page.
 
 ## Public Positioning
 
-Project Governance System is an AI-native governance layer for projects that
-work with AI agents over time.
+Project Governance System keeps long-running AI-assisted projects understandable
+and governable.
 
 Beginner-friendly description:
 
-> Git remembers code history. AGENTS.md tells an AI how to enter a project.
-> Superpowers gives engineering workflows. Project Governance System is the
-> librarian and traffic desk: it decides where durable AI-created documents
-> belong, which ones are current truth, which route a task should take, and
-> when old documents should retire.
+> AI can create plans, specifications, rules, and reports faster than people can
+> organize them. Project Governance System is the librarian, traffic desk, and
+> inspection machine: it keeps current truth easy to find, sends each task down
+> the right route, and checks that important project evidence is still connected.
 
 ## What To Emphasize
 
+- It reduces the cognitive load of returning to an AI-assisted project after
+  days, weeks, or many different AI sessions.
 - It keeps AI-generated specs, plans, decisions, references, and routing rules
   from becoming unmanaged clutter.
 - It separates central governance rules from project-local truth.
@@ -46,13 +47,18 @@ Beginner-friendly description:
   checks, router integrity, health checks, and read-only migration checks.
 - It provides `pro-gov` commands for packaged starter/profile assets,
   read-only init planning, read-only sync checks, and package health checks.
-- It is designed to work with external workflow systems instead of replacing
-  them.
+- It includes ProjectLens-style read-only inspection and a governed local agent
+  asset registry without publishing private or third-party skill bodies.
+- It works with external workflow systems instead of replacing them:
+  Superpowers owns engineering process, while Ponytail may act as an optional
+  complexity adviser with global mode `off`.
 
 ## Do Not Overclaim
 
 - Do not say it replaces Git.
 - Do not say it replaces Superpowers.
+- Do not say it requires or automatically enables Ponytail.
+- Do not promise a fixed percentage reduction in code, tokens, time, or cost.
 - Do not say it automatically migrates every project.
 - Do not imply product prompts, generated media, or runtime assets must move
   under `docs/**`.
@@ -70,11 +76,13 @@ Use the central repo's README.md, packages/doc-gov/README.md,
 packages/pro-gov/README.md, docs/reference/adoption/public-release-checklist.md,
 and docs/reference/adoption/site-publication-brief.md as source material.
 
-Position it for normal readers as an AI-era documentation governance system:
-the librarian and traffic desk for AI-created project documents. Explain what
-problem it solves, why it matters, how doc-gov checks work, and how it fits next
-to Git, AGENTS.md, Superpowers, pro-gov starter/profile distribution, and
-project-local product truth.
+Position it for normal readers as the system that keeps long-running AI-assisted
+projects understandable and governable. Lead with the pain: AI creates useful
+plans, specs, rules, and evidence faster than people can organize and retire
+them. Use the librarian, traffic desk, and inspection-machine analogy before
+technical package details. Explain how it fits next to Git, AGENTS.md,
+Superpowers, optional Ponytail advice, pro-gov starter/profile distribution,
+ProjectLens inspection, and project-local product truth.
 
 Keep the copy confident but accurate. Do not claim automatic migration or
 full replacement of existing workflow tools. npm publication is live, so include