wtf-p 0.6.0-rc.2 → 0.7.0

package/README.md

@@ -8,305 +8,187 @@
 
 Also: Proposal. Presentation. Poster.
 
-Portable, evidence-grounded academic workflows for modern coding agents.
+Human-guided research and writing workflows for AI coding agents.
 
 </div>
 
-WTF-P turns an AI coding agent into a structured research and writing system. It plans before drafting, grounds claims in evidence, isolates section context, delegates bounded work to specialist agents, and verifies the result against the approved plan.
+WTF-P gives your coding agent one portable academic method: interview the
+author, map the evidence, record decisions, build an outline, plan and draft
+one section at a time, review it, and resume later from durable state. You keep
+the scientific judgment. The agent keeps the bookkeeping and does bounded jobs.
 
-Version `0.6.0-rc.2` is the corrective release candidate for the modernized agent platform. One canonical protocol generates native resources for Clio Coder, Claude Code, Codex, GitHub Copilot CLI, OpenCode, Antigravity CLI, and Gemini CLI; RC2 tightens decision fidelity and durable write/review/pause/resume handling after supervised local-model testing.
+It ships as one canonical [Agent Plugins 1.0.0](https://agent-plugins.org)
+bundle that a deterministic compiler projects into a native package for seven
+coding-agent hosts. Version `0.7.0` is the current stable release and is
+what npm `latest` resolves to; v0.5 remains installable by explicit version.
 
-## Quick start
+**Optional CiteNexus research backend (0.7.0):** `citation-search --backend=cite-nexus`
+queries Crossref, DataCite and Europe PMC by default, plus explicitly selected academic
+APIs, through the [CiteNexus](docs/CITE_NEXUS.md) MCP server. Results keep their source
+evidence and stay candidates. CiteNexus is a separate Python package
+(`pip install cite-nexus-mcp==0.2.0`) that WTF-P never installs for you. Research
+actions reach it on Clio Coder and Claude Code; the other hosts keep their existing
+capability blockers.
 
-Install explicitly for the agent you use:
+## Install on your agent
 
-```bash
-npx wtf-p@next install clio --advanced
-npx wtf-p@next install claude --advanced
-npx wtf-p@next install codex --advanced
-npx wtf-p@next install copilot --advanced
-npx wtf-p@next install opencode --advanced
-npx wtf-p@next install antigravity --advanced
-npx wtf-p@next install gemini --advanced
-```
+Two routes. Pick one per host; both register the same plugin, so do not use
+both on the same profile.
 
-An interactive terminal can also run `npx wtf-p@next` and choose a target. A noninteractive bare invocation refuses to write anything; it requires an explicit target or scope.
+**From this repository, with the host's own plugin manager.** Claude Code,
+Codex, and Copilot CLI read a marketplace straight from the Git repository and
+load the committed envelope, so no installer runs:
 
-Then start a paper with the native WTF-P action exposed by your client. The
-following is the slash-command form used by Clio, Claude, Copilot CLI,
-OpenCode, Antigravity, and Gemini:
-
-```text
-/wtfp:new-paper
-/wtfp:create-outline
-/wtfp:plan-section 1
-/wtfp:write-section 1
-/wtfp:review-section 1
+```bash
+claude plugin marketplace add akougkas/wtf-p && claude plugin install wtfp@wtf-p
+codex plugin marketplace add akougkas/wtf-p && codex plugin add wtfp@wtf-p
+copilot plugin marketplace add akougkas/wtf-p && copilot plugin install wtfp@wtf-p
 ```
 
-These five lifecycle commands are deliberately unavailable in the Copilot
-cloud projection until that surface has an exact explicit-approval binding.
-
-Clio also ships flat `/wtfp-new-paper` compatibility prompts for current releases. The coordinated Clio integration discovers the preferred nested `/wtfp:new-paper` namespace; installation probes that capability in a credential-free disposable profile and falls back gracefully for legacy clients.
-
-Codex discovers all 36 stable method routes through seven native Agent Skills
-instead of a `/wtfp:*` command namespace. Twenty-four are adapter-available in the
-current adapter; the other 12 carry deterministic `WTFP_ACTION_UNAVAILABLE`
-references instead of unsupported workflow instructions. Select the owning
-plugin skill explicitly when the route must be unambiguous (for example,
-`$wtf-p:wtfp-start-project` followed by the `new-paper` request and its exact
-arguments). Existing user-level commands can take precedence over extension
-commands in clients that support both; use the client's discovery listing to
-confirm the reported source before testing a new installation.
-
-## First-class adapters
-
-| Target | Native envelope | Semantic actions: discoverable / adapter-available | Specialists | Skills | Target-specific capabilities |
-| --- | --- | ---: | ---: | ---: | --- |
-| Clio Coder | Extension | 36 / 24 (72 prompt aliases: 48 available) | 11 | 7 | Strict worker recipes; host-session tool policy for slash prompts; two explicit fleets |
-| Claude Code | Claude plugin | 36 / 24 | 11 | 7 | Native command permissions and plugin validation |
-| Codex | Codex plugin | 36 / 24 through skills | Host-managed | 7 | `.codex-plugin` metadata and marketplace packaging |
-| GitHub Copilot | Native CLI plugin plus committed cloud `.github` projection | CLI 36 / 24; cloud 36 / 5 | 11 | 7 | CLI discovery and cloud-safe prompts, agents, skills, and instructions |
-| OpenCode | Filesystem bundle | 36 / 24 | 11 | 7 | Native commands and agents |
-| Antigravity CLI | `agy` plugin | 36 / 24 | 11 | 7 | Commands converted to native skills by `agy` |
-| Gemini CLI | Gemini extension | 36 / 24 | 11 | 7 | TOML commands and extension context |
-
-Discovery counts stable action routes, including deterministic refusal stubs;
-it does not by itself establish behavioral support. Clio, Claude, Codex,
-Copilot CLI, OpenCode, Antigravity, and Gemini project 24 of the 36 canonical
-actions as adapter-available and return `WTFP_ACTION_UNAVAILABLE` for `analyze-bib`,
-`audit-milestone`, `check-refs`, `contribute`, `create-poster`,
-`create-slides`, `export-latex`, `remove-section`, `report-bug`,
-`request-feature`, `research-gap`, and `update`, because those actions lack an
-exact target binding for at least one declared capability or effect. The
-Copilot cloud projection marks only `add-todo`, `help`, `list-assumptions`,
-`map-project`, and `pause-writing`; it refuses the other 31 because it also
-lacks an exact explicit-approval binding. Each generated target records its
-machine-readable result in `compatibility/action-availability.json`.
-
-An available action has complete semantic capability, effect, and approval
-bindings; that is not automatically an action-scoped host tool allowlist.
-Clio 0.3.8 prompt templates expand into an ordinary main-agent turn and retain
-the session tool surface. The Clio manifest records this as
-`hostToolEnforcement.actionScoped: false`. Use `read-only` for previews or
-supervised `suggest` autonomy for mutations, and deny and stop on any tool call
-outside the action contract. A run under `auto-edit` cannot earn WTF-P's
-no-undeclared-tool safety result merely because the generated prompt told the
-model not to use shell.
-
-The adapters are generated artifacts, not seven hand-maintained copies. Every generated envelope includes a cryptographic inventory and the portable protocol resources needed to understand its workflows. Copilot additionally receives a generated, commit-ready `.github` projection for cloud/repository use.
-
-For a GitHub-hosted Copilot coding agent, review and copy the `.github/` tree from `vendors/copilot/project/` in the release archive into the target repository, then commit it through that repository's normal review process. The user-level `install copilot` command configures the CLI plugin; it deliberately does not write into an unrelated project checkout.
-
-The release-candidate native-discovery matrix was exercised with Claude Code
-2.1.251, Codex CLI 0.144.1, Copilot CLI 1.0.80, OpenCode 1.18.16,
-Antigravity 1.1.22, Gemini CLI 0.57.0, and Clio Coder 0.3.8 at merged
-commit `9b7b80cc`. Real isolated `new-paper` evaluations used Claude Sonnet
-5/xhigh, Codex GPT-5.4/xhigh (GPT-5.6 was unavailable through that CLI's
-ChatGPT-auth route), and Clio GPT-5.6 Terra/xhigh. The compiler-v4 Clio rerun
-earned 8/8 with independent validation of all five previewed records. The
-broader paid routing matrix, full lifecycle chain, and cross-version baseline
-remain separate evidence gates. See [compatibility evidence](docs/COMPATIBILITY.md)
-for exact claims and caveats. WTF-P `0.6.0-rc.1` was published to npm under
-the `next` tag on 2026-08-29; each later candidate remains a separate operator
-publication action.
-
-The first retained local-model lifecycle reading used Clio 0.3.8 with
-`dynamo/qwen3.8-27b`. Both native fleet contracts validated, but the lifecycle
-did not pass: high effort timed out before writing, and an effort-off retry
-stopped after `new-paper` because the model attempted a denied shell call and
-made 5,600 section words disagree with the 6,000-word outline target. The five
-records were individually schema-valid. See the
-[blocked evidence](evaluation/v1/evidence/clio-dynamo-lifecycle-blocked/README.md);
-the remaining lifecycle and routing roadmap items stay open. That reading
-binds the earlier WTF-P source `6b58b298`; it predates later remediation for
-exact outline totals and direct-tool use, and is not a behavioral reading of
-the later source revisions.
-
-Later post-remediation readings are retained separately because they bind
-different WTF-P commits. At `0245818`, exact `/wtfp:new-paper` arguments arrived
-but the model listed excluded `.git` metadata, read an absolute host Clio
-documentation path, looped on agent discovery, and produced no planning
-records. Those accesses were read-only; zero mutating and network effects were
-applied. At `b4f0543`, the plan/check fleet completed structurally but its
-semantic checks were ungrounded. The `cbba38c` manuscript-path projection
-observation placed draft/review manuscript and summary files in the correct
-roots with no boundary violation, but drafted without the required approved
-plan, left portable state unreconciled, and failed its word target. See the
-[retained RC readings](evaluation/v1/evidence/clio-dynamo-rc-readings/README.md).
-Neither the full lifecycle nor a semantic fleet pass is claimed.
-
-A final current-source Dynamo reading at `bf50e23` created exactly five
-initialization records and passed literal schema validation 5/5. It still
-failed the release gate: the outline placed a dependency in the same wave, and
-the model made three successful shell calls plus ten denied shell retries
-despite an explicit no-shell policy. The operator stopped the run before
-`map-project`; no terminal receipt or trustworthy numeric cost exists. See the
-[current-source blocked evidence](evaluation/v1/evidence/clio-dynamo-current-source-blocked/README.md).
-
-The later operator-observed NSF 25-531 toy UAT used Clio Coder 0.3.8 and
-Dynamo `qwen3.8-27b-dynamo` with thinking off in a disposable offline profile.
-It continued an already mapped fixture through outline, discussion, plan,
-write, review, and durable pause for one section during defect-finding before
-the final RC2 write/review/pause hardening. The provisional section's persisted
-writer/state count was 1,019 whitespace-delimited words; the independent
-reviewer used a different tokenizer and counted 1,026. Its review retained four
-author-accepted warning items, and 25/25 portable JSON records passed
-independent schema validation.
-The first genuinely fresh-process resume attempt did not pass: the pre-
-hardening workflow skipped required durable reads and the author gate and
-described mutations that never occurred. With the regenerated RC2 bundle, a
-new process read the durable records, invoked the real Clio `ask_user`
-interview, waited for the author choice, resolved the checkpoint, advanced
-state to revision 7/active while preserving phase `reviewing`, and read both
-records back; independent validation remained 25/25. This is a corrected
-one-section resumption observation, not an end-to-end rerun of the final RC2
-write/review/pause contracts, full proposal, completed research, submission-
-readiness, safety-certification, or improved-writing claim. The final contracts
-have deterministic regression evidence; only resume/progress received the
-post-hardening model rerun.
-
-## The paper lifecycle
-
-WTF-P keeps the human in control while making the repeatable work deterministic:
-
-1. `/wtfp:new-paper` captures research questions, intended contribution, evidence, audience, venue, and constraints.
-2. `/wtfp:map-project` indexes existing drafts, sources, data, figures, and decisions.
-3. `/wtfp:create-outline` turns the argument into sections, dependencies, and word budgets.
-4. `/wtfp:research-gap` and `/wtfp:analyze-bib` define the canonical research methods, but current adapters return `WTFP_ACTION_UNAVAILABLE` until exact logical-tool bindings exist. Available project actions can map supplied sources; placeholders must never be represented as completed research.
-5. `/wtfp:plan-section` creates a traceable section plan and can send it through an independent plan checker.
-6. `/wtfp:write-section` drafts from the approved plan in bounded context.
-7. `/wtfp:review-section`, `/wtfp:verify-work`, and `/wtfp:polish-prose` check argument coverage, evidence, coherence, venue requirements, and prose quality.
-8. `/wtfp:audit-milestone`, `/wtfp:export-latex`, `/wtfp:create-slides`, and `/wtfp:create-poster` prepare deliverables.
-
-Use the native help route—`/wtfp:help` on slash-command clients—to inspect all
-36 stable action contracts. Executable availability is target-specific and
-recorded in the generated compatibility manifest.
-
-## What became portable
-
-The canonical source lives under `protocol/` and has four parts:
-
-- A versioned `.planning` project protocol with 11 JSON schemas and ten templates for the project manifest, configuration, state, sources, evidence, decisions, outline, sections, checkpoints, and validation results.
-- Seven standard Agent Skills for starting a project, literature research, section planning, section writing, manuscript review, project management, and research delivery.
-- Thirty-six semantic action contracts declaring inputs, reads, outputs, specialist delegation, tools, effects, and approval boundaries.
-- Eleven host-neutral specialist roles with strict mutation or verification result contracts.
-
-Concrete model names and client tool syntax do not live in canonical workflow prose. Each adapter maps semantic needs such as filesystem access, research search, user interaction, and delegation into the active client's capabilities.
-
-## Project state
-
-New workflows use a versioned `.planning/` directory. Its records are JSON-schema validated and designed to survive movement between clients:
-
-```text
-.planning/
-├── project.json
-├── config.json
-├── state.json
-├── decisions.json
-├── structure/outline.json
-├── sources/*.json
-├── evidence/*.json
-├── sections/*/section.json
-├── checkpoints/*.json
-└── validations/*.json
-```
+Codex still needs the eleven role agents copied to `$CODEX_HOME/agents/`,
+because Codex plugins do not carry agents; the npm installer does that for
+you, the Git route does not.
 
-The protocol records evidence separately from prose and records author decisions explicitly. That lets a reviewer trace a claim back to a source and lets a different agent resume without guessing what the author intended.
+**From npm, with the WTF-P installer.** You need Node.js 20 or newer and one
+supported host. Run one line. The installer publishes the generated package
+into that host's own configuration root, records an exact-file receipt, and
+registers it with the host's native plugin lifecycle where one exists.
 
-## Installation safety
+| Host | Install | Native registration the installer performs | Verified with |
+| --- | --- | --- | --- |
+| Clio Coder (0.4.7 or newer) | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install clio` | `clio-coder library install <staged-bundle> --user`, then `clio-coder library inspect wtfp --user --json` | 0.4.9 (local build) |
+| Claude Code | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install claude` | `claude plugin marketplace add <root>/marketplaces/wtfp --scope user`, then `claude plugin install wtfp@wtfp --scope user -y` | 2.1.274 |
+| Codex | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install codex` | `codex plugin marketplace add <root>/marketplaces/wtfp`, then `codex plugin add wtfp@wtfp --json`; agents copied to `$CODEX_HOME/agents/` | 0.153.3 |
+| GitHub Copilot CLI | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install copilot` | `copilot plugin marketplace add <root>/marketplaces/wtfp`, then `copilot plugin install wtfp@wtfp` | 1.0.85 |
+| OpenCode | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install opencode` | Files under the OpenCode config root; OpenCode discovers them by directory | 1.18.31 |
+| Antigravity CLI | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install antigravity` | `agy plugin install <root>/sources/wtfp` | 1.2.5 |
+| Gemini CLI | `npx --yes --package=wtf-p@0.7.0 -- wtf-p install gemini` | Files under `<root>/extensions/wtfp`; Gemini discovers the extension by directory | 0.60.0 |
 
-The `0.6` installer is an ownership-aware transaction engine:
+"Verified" means native discovery in a disposable profile on this exact
+envelope, with the commands recorded in
+[Host capabilities](docs/HOST_CAPABILITIES.md). Clio Coder is published as
+`@iowarp/clio-coder`; 0.4.7 and newer carry the plugin engine WTF-P uses.
 
-- It rejects filesystem roots, the home directory itself, the repository root, traversal, and symlink escapes.
-- It snapshots package sources and refuses source or destination path races.
-- It publishes files atomically where possible and rolls back a failed transaction.
-- It compensates native marketplace/plugin registration if a later activation step fails.
-- It does not register a partial adapter when any conflicting file was preserved.
-- It records only files it actually wrote, with SHA-256 hashes, adapter-contract v1, and generator-v4 metadata, in a v2 receipt.
-- Reinstallation cannot claim ownership of files it skipped.
-- Uninstall removes exact unchanged owned files. It preserves modified files and unrelated siblings by default.
-- Dry runs are byte-preserving.
+Keep the explicit `--package=wtf-p@<version> -- wtf-p` form. On a workstation
+with WTF-P 0.5 installed globally, the shorter `npx wtf-p@<version>` can run
+the old executable instead.
 
-Use a custom isolated client root when evaluating an adapter:
+## Sixty-second start
 
 ```bash
-CODEX_HOME=/tmp/wtfp-codex npx wtf-p install codex --advanced
-CLIO_CODER_CONFIG_DIR=/tmp/wtfp-clio npx wtf-p install clio --advanced
+npx --yes --package=wtf-p@0.7.0 -- wtf-p install clio
+cd /path/to/your-paper-or-proposal
+clio-coder --autonomy suggest
 ```
 
-Inspect or remove an installation with:
-
-```bash
-npx wtf-p status
-npx wtf-p doctor
-npx wtf-p uninstall --clio --dry-run
-npx wtf-p uninstall --clio --yes
+```text
+/wtfp:help
+/wtfp:new-paper I am preparing a research proposal on reproducible scientific workflows. Interview me before deciding the scope, claims, evaluation, team, budget, or timeline. Use only the evidence I provide and mark unknowns instead of inventing citations.
 ```
 
-The legacy `--global`, `--local`, `--claude`, `--gemini`, and `--opencode` selectors remain compatibility aliases during the release-candidate cycle.
+The agent interviews you, previews the five initial project records, and waits
+for your approval before writing anything. Every host uses the same
+`/wtfp:<action>` names except Codex, which exposes the same actions through
+seven native skills: mention `$wtfp-start-project` and ask for the
+`new-paper` action with the same brief.
 
-## Developing adapters
+A normal project then moves one action at a time:
 
-Edit canonical resources under `protocol/`, then regenerate every native projection:
+```text
+/wtfp:map-project        inventory the materials you supplied
+/wtfp:create-outline     argument, dependencies, exact word budget, for approval
+/wtfp:discuss-section    capture your intent for one section
+/wtfp:plan-section       one checked, executable plan
+/wtfp:write-section      draft only from the approved plan and evidence
+/wtfp:review-section     independent review, findings recorded, nothing rewritten
+/wtfp:pause-writing      durable handoff; quit the client
+/wtfp:resume-writing     a fresh process picks up from disk
+```
 
-```bash
-npm run build:adapters
-npm run check:adapters
-npm test
-npm run test:integration
+See [Getting started](docs/GETTING_STARTED.md) for each host's launch command,
+Codex skill selectors, isolated evaluation profiles, and troubleshooting.
+
+## What it writes
+
+Four document types share the same action set and differ in their scaffold:
+
+| Workflow | Scaffold | Entry actions |
+| --- | --- | --- |
+| Paper (article, conference, review, thesis chapter) | `protocol/templates/paper-outline.md` | `new-paper`, `create-outline` |
+| Grant proposal (solicitation-driven) | `protocol/templates/grant-proposal-outline.md` | `new-paper`, `create-outline`; see the [proposal workflow](docs/PROPOSAL_WORKFLOW.md) |
+| Poster | `protocol/templates/poster.md` | `create-poster` |
+| Presentation | `protocol/templates/slides.md` | `create-slides` |
+
+The catalog has 36 stable actions across seven skills: start a project,
+research the literature, plan a section, write a section, review the
+manuscript, manage the project, and deliver. Availability is decided per host
+by the generated `compatibility/action-availability.json`, and an unavailable
+action returns `WTFP_ACTION_UNAVAILABLE` instead of improvising:
+
+| Host | Available | Fails closed |
+| --- | ---: | --- |
+| Clio Coder, Claude Code | 31 / 36 | `contribute`, `report-bug`, `request-feature` (no `external.issue` binding); `remove-section` (no `filesystem.delete`); `update` (no `package.update`) |
+| Codex, Copilot CLI, OpenCode, Antigravity, Gemini | 26 / 36 | the five above plus `research-gap`, `analyze-bib`, `check-refs`, `audit-milestone`, `export-latex`, whose `tool.execute` effect is bound only to Clio `bash` and Claude `Bash` |
+| Copilot cloud projection (`.github`) | 5 / 36 | everything that needs an explicit approval gate |
+
+Where the research routes are available, `tool.execute` authorizes exactly one
+command, the bundled `tools/wtfp-tool.js` dispatcher over seven bibliography
+and citation tools. Run it with `--offline` until you approve network use.
+
+## What it will not do
+
+- It does not write without you. Outline, plan, write, review, and delivery
+  gates are on by default, and a gate is crossed only through the host's real
+  interaction tool, never by silence or a model's own recommendation.
+- It does not invent evidence. Sources and evidence are separate records with
+  provenance; a missing citation stays missing.
+- It does not render or compile. `create-poster`, `create-slides`, and
+  `export-latex` emit source and hand you the render or compile command.
+- It does not submit. `submit-milestone` writes a local archive, not a
+  submission to a funder, journal, or service.
+- It does not touch Git or publish. No WTF-P action initializes, commits,
+  branches, pushes, tags, or publishes as a side effect.
+- It does not claim more than it has observed. Native discovery is verified
+  per host; model-backed lifecycle evidence is partial and listed in
+  [Compatibility](docs/COMPATIBILITY.md).
+
+## How it is built
+
+One protocol, one compiler, seven projections. Humans edit `protocol/`; the
+compiler owns every file under `vendors/`, authenticates each envelope with a
+SHA-256 inventory, and fails closed when a host cannot bind a capability an
+action requires.
+
+```mermaid
+flowchart LR
+  P["protocol/<br/>36 action contracts, 36 workflows,<br/>11 roles, 7 skills, .planning v1 schemas,<br/>templates, tools.json"] --> C["adapter compiler<br/>bin/lib/adapter-compiler.js"]
+  C --> B["vendors/plugin<br/>canonical Agent Plugins 1.0.0 bundle<br/>(Clio route)"]
+  C --> H["vendors/claude · codex · copilot ·<br/>opencode · antigravity · gemini<br/>native projections"]
+  B --> I["npx wtf-p install &lt;host&gt;<br/>exact-file receipts, native registration"]
+  H --> I
 ```
 
-`check:adapters` fails when committed generated resources drift from their canonical inputs. The test suite also checks action parity, skills, portable roles, `.planning` schemas, resource containment, exact installer ownership, rollback, uninstall preservation, and native envelope structure.
-
-The Clio reference integration is merged into Clio Coder `v0.3.8` at
-`9b7b80cc`. It adds recursive namespaced extension prompts, extension-owned
-agents and fleets, same-extension skill binding, contained `${extensionRoot}`
-resource resolution, exact operator-argument preservation, preservation of
-nested template `state.json` resources, and extension-aware fleet preflight.
-Effective package discovery certifies 72 prompts (36 nested and 36 flat), 11
-agents, seven skills, two fleets, and zero diagnostics. Of those prompts, 48
-aliases represent 24 adapter-available semantic actions and 24 aliases are the nested
-and flat forms of 12 deterministic refusal routes. WTF-P capability-probes that
-surface because Clio currently records, but does not enforce,
-`compatibility.clio`. The generated fleet contracts use directory boundaries
-(`.planning/` and `paper/`) so nested writes are authorized without broadening
-the worker sandbox.
-
-The two Clio fleets are operator-invoked native primitives, not implicit
-routes behind `/wtfp:*`. Use
-`clio-coder fleet run wtfp-plan-section --var section=<id>` or
-`clio-coder fleet run wtfp-draft-review --var section=<id>` when their narrower
-specialist contracts are appropriate; the slash-command orchestrator remains
-responsible for approval and portable-state reconciliation around those worker
-steps.
-
-## Design principles
-
-- Evidence before eloquence: a fluent paragraph is not a substitute for a supported claim.
-- Specification before drafting: author intent and acceptance criteria remain explicit.
-- Portable semantics, native ergonomics: share the method while respecting each client's real plugin model.
-- Bounded delegation: specialists receive the minimum context and authority their task requires.
-- Human approval at consequential boundaries: deletion, commits, merges, package updates, and external issue creation remain explicit effects.
-- Reversible installation: WTF-P never treats an agent's whole configuration directory as its property.
-
-## Origin
-
-WTF-P was built at the [Gnosis Research Center](https://grc.iit.edu/) at Illinois Tech for research teams with papers to publish, grants to win, and no time for writer's block.
-
-## Links
-
-- [Changelog](CHANGELOG.md)
-- [Modernization architecture](docs/agent-platform-modernization.md)
-- [Compatibility evidence](docs/COMPATIBILITY.md)
-- [Behavioral evaluation methodology](evaluation/README.md)
-- [Tool execution and MCP decision](docs/adr/0001-hybrid-tool-execution.md)
-- [v0.5 → v0.6 migration guide](docs/MIGRATION_V05_TO_V06.md)
-- [Build and release](docs/BUILD_AND_RELEASE.md)
-- [Contributing](CONTRIBUTING.md)
-- [Roadmap](ROADMAP.md)
-- [License](LICENSE)
-- [GitHub](https://github.com/akougkas/wtf-p)
+Project memory lives in the paper directory: control records under
+`.planning/` (project, config, state, decisions, outline, sources, evidence,
+sections, checkpoints, validations) and manuscript artifacts under `paper/`.
+Another process, or another supported host, resumes from those files rather
+than from chat history.
+
+## Learn more
+
+- [Documentation index](docs/README.md)
+- [Getting started](docs/GETTING_STARTED.md)
+- [Host capabilities and verification commands](docs/HOST_CAPABILITIES.md)
+- [Proposal workflow](docs/PROPOSAL_WORKFLOW.md)
+- [Migrating from v0.5](docs/MIGRATION_V05_TO_V06.md)
+- [Compatibility and evidence](docs/COMPATIBILITY.md)
+- [Packaging and the Clio plugin lifecycle](docs/AGENT_PLUGIN.md)
+- [Building and releasing](docs/BUILD_AND_RELEASE.md)
+- [Changelog](CHANGELOG.md) and [Contributing](CONTRIBUTING.md)
+
+WTF-P was built at the [Gnosis Research Center](https://grc.iit.edu/) at
+Illinois Tech for research teams with papers to publish, grants to win, and no
+time for writer's block.
 
 <div align="center">
 

package/bin/commands/install-logic.js

@@ -56,6 +56,10 @@ function getVendorDir(runtime, explicitConfigDir) {
       : resolvedEnvironmentRoot;
   }
 
+  if (typeof vendorConfig.resolveConfigRoot === 'function') {
+    return expandTilde(vendorConfig.resolveConfigRoot(process.env));
+  }
+
   return path.join(os.homedir(), vendorConfig.defaultDir);
 }
 
@@ -260,7 +264,7 @@ async function installWithConflictResolution(files, pathPrefix, targetDir, optio
       if (file.name === 'plugin.json' && file.componentId === 'plugin' && exists) {
         try {
           const existing = JSON.parse(existingSnapshot.bytes.toString('utf8'));
-          if (existing.name && existing.name !== 'wtf-p' && existing.name !== 'write-the-f-paper') {
+          if (existing.name && existing.name !== 'wtfp' && existing.name !== 'wtf-p' && existing.name !== 'write-the-f-paper') {
             out.verbose(`  ${c.yellow('!')} ${c.dim(relDest)} belongs to another plugin — skipped`);
             stats.skipped++;
             continue;
@@ -604,8 +608,10 @@ async function install(runtime, isUpdate, options, pkg) {
   const isGlobal = runtime !== 'claude-local';
   const locationLabel = getPathLabel(targetDir, isGlobal);
 
-  const configuredByEnvironment = typeof process.env[vendorConfig.configDirEnv] === 'string' &&
-    process.env[vendorConfig.configDirEnv].trim().length > 0;
+  const configuredByEnvironment = (typeof process.env[vendorConfig.configDirEnv] === 'string' &&
+    process.env[vendorConfig.configDirEnv].trim().length > 0) ||
+    (typeof vendorConfig.resolveConfigRoot === 'function' &&
+      path.resolve(expandTilde(vendorConfig.resolveConfigRoot(process.env))) !== path.join(os.homedir(), vendorConfig.defaultDir));
   const pathPrefix = isGlobal
     ? ((explicitConfigDir || configuredByEnvironment)
       ? `${targetDir}${path.sep}`
@@ -728,7 +734,9 @@ async function install(runtime, isUpdate, options, pkg) {
     if (stats.writtenFiles.length > 0) {
       writeVersionFile(targetDir, pkg.version, stats.writtenFiles, {
         runtime: vendorKey,
-        scope: isGlobal ? (explicitConfigDir ? 'custom' : 'user') : 'project',
+        scope: vendorKey === 'clio' && targetDir === path.join(process.cwd(), '.clio-coder')
+          ? 'project'
+          : isGlobal ? (explicitConfigDir ? 'custom' : 'user') : 'project',
         skipped: stats.skipped,
         selectionComplete: onlyInstall === 'all',
         adapterVersion: ADAPTER_CONTRACT_VERSION,
@@ -737,6 +745,10 @@ async function install(runtime, isUpdate, options, pkg) {
       });
     }
     stats.commit();
+    if (typeof nativeActivation.commit === 'function') {
+      const warning = nativeActivation.commit();
+      if (warning) out.warn(warning);
+    }
   } catch (error) {
     const nativeRollbackFailures = Array.isArray(error.nativeRollbackFailures)
       ? [...error.nativeRollbackFailures]
@@ -768,12 +780,21 @@ async function install(runtime, isUpdate, options, pkg) {
   }
 
   if (nativeRequested) {
+    if (nativeActivation.notice && !hasQuiet) out.warn(nativeActivation.notice);
     if (nativeActivation.status === 'unavailable' && !hasQuiet) {
       out.warn(`${nativeActivation.executable} is not installed; the WTF-P bundle is staged but native registration is pending.`);
+      if (vendorKey === 'clio') {
+        // Clio refuses a source that overlaps its managed destination, so the
+        // published tree itself can never be the install source. Re-running
+        // the installer stages a distinct copy and registers it.
+        const scope = targetDir === path.join(process.cwd(), '.clio-coder') ? 'project' : 'user';
+        const configFlag = explicitConfigDir ? ` --config-dir '${targetDir.replaceAll("'", "'\\''")}'` : '';
+        out.warn(`Activation is pending: once clio-coder is on PATH, re-run npx wtf-p install clio${configFlag} from this directory to register the ${scope}-scope plugin.`);
+      }
     } else if (nativeActivation.status === 'deferred' && !hasQuiet) {
       out.warn(`${nativeActivation.reason}. The WTF-P bundle is staged but native registration is pending.`);
     } else if (nativeActivation.status === 'incompatible' && !hasQuiet) {
-      out.warn(`The installed Clio version does not expose the complete WTF-P extension contract: ${nativeActivation.reason}. Flat prompts and skills remain staged; upgrade Clio for agents, fleets, and namespaced prompts.`);
+      out.warn(`${vendorConfig.name} did not accept the WTF-P package: ${nativeActivation.reason}. The bundle remains staged, not activated.`);
     }
   }
 
@@ -787,15 +808,23 @@ async function install(runtime, isUpdate, options, pkg) {
       out.log(`
   ${c.green('Done!')} ${c.dim(`[${vendorConfig.name}]`)} Installed: ${stats.installed}, Skipped: ${stats.skipped}, Backed up: ${stats.backed}
 
-  Run ${c.cyan('/wtfp:help')} in ${vendorConfig.name} to get started.
+  ${vendorKey === 'codex'
+    ? `Select ${c.cyan('$wtfp-start-project')} in ${vendorConfig.name} and request the new-paper action to get started.`
+    : `Run ${c.cyan('/wtfp:help')} in ${vendorConfig.name} to get started.`}
 `);
     }
 
     if (stats.installed > 0 && showExplanations && !isUpdate) {
       out.log(`  ${c.yellow('Get started:')}`);
-      out.log(`    ${c.cyan('/wtfp:new-paper')}      Define your paper's vision and structure`);
-      out.log(`    ${c.cyan('/wtfp:progress')}       See where you are and what's next`);
-      out.log(`    ${c.cyan('/wtfp:help')}           Browse all available commands\n`);
+      if (vendorKey === 'codex') {
+        // Codex exposes skills, not slash commands.
+        out.log(`    ${c.cyan('$wtfp-start-project')}   Define your paper's vision and structure (request new-paper)`);
+        out.log(`    ${c.cyan('$wtfp-manage-project')}  See where you are and what's next (request progress)\n`);
+      } else {
+        out.log(`    ${c.cyan('/wtfp:new-paper')}      Define your paper's vision and structure`);
+        out.log(`    ${c.cyan('/wtfp:progress')}       See where you are and what's next`);
+        out.log(`    ${c.cyan('/wtfp:help')}           Browse all available commands\n`);
+      }
     }
   }