@blxzer/pactile 0.5.0 → 0.6.0-beta.2

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workflow.md

@@ -1,75 +1,75 @@
-# Local Workflow System
-
-`.pactile/workflow.md` is the Pactile workflow source of truth inside the user project. An AI does not need Pactile source code to understand how the current project should move tasks forward; this file is enough.
-
-## File Responsibilities
-
-`.pactile/workflow.md` has three responsibilities:
-
-1. **Explain workflow phases**: Plan, Execute, Finish.
-2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
-3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
-
-## Current Phase Model
-
-```text
-Phase 1: Plan    -> clarify what to build, produce prd.md and required research
-Phase 2: Execute -> implement against the PRD and specs, then check
-Phase 3: Finish  -> final verification, preserve lessons, and wrap up
-```
-
-Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
-
-## Skill Routing
-
-`workflow.md` separates routing by platform capability:
-
-- Platforms with sub-agent support: dispatch `pactile-implement` by default for implementation and `pactile-check` for checking.
-- Platforms without sub-agent support: the main session reads skills such as `pactile-before-dev`, then executes directly.
-
-When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
-
-## Workflow-State Prompt Blocks
-
-The bottom of `workflow.md` can contain state blocks like this:
-
-```text
-[workflow-state:no_task]
-...
-[/workflow-state:no_task]
-```
-
-Hooks choose the right block based on selected task status and inject it into the conversation. Common states include:
-
-| State | Meaning |
-| --- | --- |
-| `no_task` | The current session has no selected task. |
-| `planning` | The task is still in requirements, research, or context configuration. |
-| `in_progress` | The task has entered implementation and checking. |
-| `completed` | The task is complete and waiting for wrap-up or archive. |
-
-If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
-
-## Local Modification Patterns
-
-Common changes:
-
-| Goal | Edit point |
-| --- | --- |
-| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
-| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
-| Change the default implementation/check path | Update Phase 2 and skill routing. |
-| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
-| Change platform differences | Update routing descriptions grouped by platform. |
-
-After editing, make the AI reread `.pactile/workflow.md`; do not assume the flow from the old conversation is still valid.
-
-## Relationship To Platform Files
-
-`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
-
-- skills, such as `pactile-brainstorm` and `pactile-check`.
-- commands/prompts/workflows, such as continue and finish-work.
-- hooks, such as session-start or workflow-state injection.
-
-If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.
+# Local Workflow System
+
+`.pactile/workflow.md` is the Pactile workflow source of truth inside the user project. An AI does not need Pactile source code to understand how the current project should move tasks forward; this file is enough.
+
+## File Responsibilities
+
+`.pactile/workflow.md` has three responsibilities:
+
+1. **Explain workflow phases**: Plan, Execute, Finish.
+2. **Define skill routing**: which skill or agent the AI should use when the user expresses a certain intent.
+3. **Provide workflow-state prompt blocks**: hooks can inject the prompt block for the current state into the conversation.
+
+## Current Phase Model
+
+```text
+Phase 1: Plan    -> clarify what to build, produce prd.md and required research
+Phase 2: Execute -> implement against the PRD and specs, then check
+Phase 3: Finish  -> final verification, preserve lessons, and wrap up
+```
+
+Each phase contains numbered steps, such as `1.3 Configure context`. These numbers are not runtime fields in `task.json`; they are workflow structure for AI and humans to read.
+
+## Skill Routing
+
+`workflow.md` separates routing by platform capability:
+
+- Platforms with sub-agent support: dispatch `pactile-implement` by default for implementation and `pactile-check` for checking.
+- Platforms without sub-agent support: the main session reads skills such as `pactile-before-dev`, then executes directly.
+
+When changing local AI behavior, update the routing descriptions in `workflow.md` first, then check whether the corresponding platform skill, command, or agent files need to stay in sync.
+
+## Workflow-State Prompt Blocks
+
+The bottom of `workflow.md` can contain state blocks like this:
+
+```text
+[workflow-state:no_task]
+...
+[/workflow-state:no_task]
+```
+
+Hooks choose the right block based on selected task status and inject it into the conversation. Common states include:
+
+| State | Meaning |
+| --- | --- |
+| `no_task` | The current session has no selected task. |
+| `planning` | The task is still in requirements, research, or context configuration. |
+| `in_progress` | The task has entered implementation and checking. |
+| `completed` | The task is complete and waiting for wrap-up or archive. |
+
+If the user wants to change policies such as "whether to create a task when there is no task," "when task creation may be skipped," or "whether sub-agents are required," edit these state blocks and the routing table above them.
+
+## Local Modification Patterns
+
+Common changes:
+
+| Goal | Edit point |
+| --- | --- |
+| Add a phase | Update the Phase Index, phase body, routing, and state blocks. |
+| Change task creation policy | Update the `no_task` state block and Phase 1 description. |
+| Change the default implementation/check path | Update Phase 2 and skill routing. |
+| Change the wrap-up flow | Update Phase 3 and `finish-work` related descriptions. Note the current split: Phase 3.4 = AI-driven code commits (batched, user-confirmed), Phase 3.5 = `/finish-work` (archive + record session). `/finish-work` refuses to run if the working tree is dirty. |
+| Change platform differences | Update routing descriptions grouped by platform. |
+
+After editing, make the AI reread `.pactile/workflow.md`; do not assume the flow from the old conversation is still valid.
+
+## Relationship To Platform Files
+
+`workflow.md` is the semantic center of the local workflow, but each platform can also have its own entry files:
+
+- skills, such as `pactile-brainstorm` and `pactile-check`.
+- commands/prompts/workflows, such as continue and finish-work.
+- hooks, such as session-start or workflow-state injection.
+
+If only `workflow.md` changes, platform entry files may still contain old language. When the user wants to change "what the AI actually does," also inspect the relevant platform directory.

package/dist/templates/common/bundled-skills/pactile-meta/references/local-architecture/workspace-memory.md

@@ -1,71 +1,71 @@
-# Local Workspace Memory System
-
-`.pactile/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
-
-## Directory Structure
-
-```text
-.pactile/workspace/
-├── index.md
-└── <developer>/
-    ├── index.md
-    ├── journal-1.md
-    └── journal-2.md
-```
-
-| File | Purpose |
-| --- | --- |
-| `.pactile/.developer` | Current developer identity. |
-| `.pactile/workspace/index.md` | Global workspace overview. |
-| `.pactile/workspace/<developer>/index.md` | Session index for a developer. |
-| `.pactile/workspace/<developer>/journal-N.md` | Session journal. |
-
-## Developer Identity
-
-Run this the first time:
-
-```bash
-python3 ./.pactile/scripts/init_developer.py <name>
-```
-
-This creates `.pactile/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
-
-## Journal
-
-`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
-
-Common command for recording a session:
-
-```bash
-python3 ./.pactile/scripts/add_session.py \
-  --title "Session title" \
-  --summary "What changed" \
-  --commit "abc1234"
-```
-
-Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
-
-## Relationship Between Workspace Memory And Tasks
-
-| System | What it stores |
-| --- | --- |
-| `.pactile/tasks/` | Requirements, design, research, and state for a specific task. |
-| `.pactile/workspace/` | Work records across tasks and sessions. |
-| `.pactile/spec/` | Engineering knowledge preserved as long-term conventions. |
-
-If information is only useful for the selected task, put it in the task directory.
-If information describes what happened in the current session, put it in the workspace journal.
-If information should be followed every time code is written in the future, put it in spec.
-
-## Local Customization Points
-
-| Need | Edit location |
-| --- | --- |
-| Change maximum journal lines | `max_journal_lines` in `.pactile/config.yaml`. |
-| Change session auto-commit message | `session_commit_message` in `.pactile/config.yaml`. |
-| Change session content format | `.pactile/scripts/add_session.py`. |
-| Change how workspace is displayed in context | `.pactile/scripts/common/session_context.py`. |
-
-## AI Usage Rules
-
-The AI should not treat workspace as the only source of truth. When resuming a task, read the selected task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.
+# Local Workspace Memory System
+
+`.pactile/workspace/` stores cross-session memory. Its purpose is to let AI and humans understand what happened before across different windows and different days.
+
+## Directory Structure
+
+```text
+.pactile/workspace/
+├── index.md
+└── <developer>/
+    ├── index.md
+    ├── journal-1.md
+    └── journal-2.md
+```
+
+| File | Purpose |
+| --- | --- |
+| `.pactile/.developer` | Current developer identity. |
+| `.pactile/workspace/index.md` | Global workspace overview. |
+| `.pactile/workspace/<developer>/index.md` | Session index for a developer. |
+| `.pactile/workspace/<developer>/journal-N.md` | Session journal. |
+
+## Developer Identity
+
+Run this the first time:
+
+```bash
+pactile init --user <name>
+```
+
+This creates `.pactile/.developer` and the corresponding workspace directory. The AI should not change developer identity casually; if the identity is wrong, first confirm who is using the current project.
+
+## Journal
+
+`journal-N.md` records completed or partially completed work from each session. By default, each journal holds about 2000 lines; after that it rotates to the next file.
+
+Common command for recording a session:
+
+```bash
+pactile session add \
+  --title "Session title" \
+  --summary "What changed" \
+  --commit "abc1234"
+```
+
+Planning or review work without a commit can also be recorded by using `--no-commit` or an empty commit value.
+
+## Relationship Between Workspace Memory And Tasks
+
+| System | What it stores |
+| --- | --- |
+| `.pactile/tasks/` | Requirements, design, research, and state for a specific task. |
+| `.pactile/workspace/` | Work records across tasks and sessions. |
+| `.pactile/spec/` | Engineering knowledge preserved as long-term conventions. |
+
+If information is only useful for the selected task, put it in the task directory.
+If information describes what happened in the current session, put it in the workspace journal.
+If information should be followed every time code is written in the future, put it in spec.
+
+## Local Customization Points
+
+| Need | Edit location |
+| --- | --- |
+| Change maximum journal lines | `max_journal_lines` in `.pactile/config.yaml`. |
+| Change session auto-commit message | `session_commit_message` in `.pactile/config.yaml`. |
+| Change session content format | Pactile CLI `pactile session add` implementation. |
+| Change how workspace is displayed in context | Pactile CLI `pactile context` implementation. |
+
+## AI Usage Rules
+
+The AI should not treat workspace as the only source of truth. When resuming a task, read the selected task first, then use workspace for background. After a task is complete, record important process notes in workspace; if long-term rules emerged, update spec.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/agents.md

@@ -1,69 +1,7 @@
-# Agents
-
-Pactile agent files define specialized roles. Common Pactile agents in a user project are:
-
-- `pactile-research`
-- `pactile-implement`
-- `pactile-check`
-
-Responsibility boundaries should stay consistent regardless of file format.
-
-> Pactile previously shipped agent files in per-platform directories for many AI tools (`.claude/agents/`, `.codex/agents/`, `.kiro/agents/`, etc.). The project has converged on **Cursor-only**. New agent definitions ship into `.cursor/agents/`; legacy agent directories in upgraded projects are preserved but not extended.
-
-## Agent Responsibilities
-
-| Agent | Responsibility |
-| --- | --- |
-| `pactile-research` | Investigate the question and write findings into the selected task's `research/`. |
-| `pactile-implement` | Implement against `prd.md`, optional `design.md` / `implement.md`, `implement.jsonl`, and related spec/research. |
-| `pactile-check` | Review changes, fix discovered issues, and run necessary checks. |
-
-Agent files should not become generic chat prompts. They should define input sources, write boundaries, whether code may be changed, and how results are reported.
-
-## Common Paths (Cursor)
-
-| Platform | Agent path |
-| --- | --- |
-| Cursor | `.cursor/agents/pactile-*.md` |
-
-Agent files are dispatched via the Cursor Task tool, opened as Agent sessions, or invoked inline as Skill forms depending on the entry point. See `cursor-subagent-policy.md.txt` for the full entry-point matrix and Method 1–2.6 model dispatch strategy.
-
-## Two Context Loading Modes
-
-### hook push
-
-The Cursor hook (`inject-subagent-context.py`, registered in `.cursor/hooks.json`) injects task context before the agent starts. The agent file itself can focus more on responsibilities and boundaries.
-
-### agent pull
-
-The agent file instructs the agent to read after startup:
-
-- `python3 ./.pactile/scripts/task.py selected --source`
-- `implement.jsonl` or `check.jsonl`
-- spec/research files referenced by JSONL
-- selected task `prd.md`
-- `design.md` if present
-- `implement.md` if present
-
-This mode fits cases where the hook cannot reliably rewrite the sub-agent prompt or the entry point is an Agent session that bypasses the Task hook path.
-
-## Local Change Scenarios
-
-| User need | Edit location |
-| --- | --- |
-| Implement agent must follow extra restrictions | `.cursor/agents/pactile-implement.md`. |
-| Check agent must run project-specific commands | `.cursor/agents/pactile-check.md`, and `.pactile/spec/` if needed. |
-| Research agent must output a fixed format | `.cursor/agents/pactile-research.md`. |
-| Agent cannot read task context | Agent prelude in the agent file, or the `inject-subagent-context` hook registration in `.cursor/hooks.json`. |
-| Add a project-specific agent | `.cursor/agents/` + related skill/command entry point that invokes it. |
-
-## Modification Principles
-
-1. **Keep responsibilities single-purpose**. Do not mix research, implement, and check responsibilities into one agent.
-2. **Specify the read order**. Agents must know to start from the selected task, read jsonl/spec context, then read `prd.md`, `design.md` if present, and `implement.md` if present.
-3. **Specify write boundaries**. Research usually only writes `research/`; implement can write code; check can fix issues.
-4. **Treat dogfood + published copies consistently**. `.cursor/agents/pactile-*.md` (dogfooded) and `packages/cli/src/templates/cursor/agents/pactile-*.md` (published template) must stay in sync — see `cross-layer-thinking-guide.md.txt` → Cross-Package Template Consistency.
-
-## Do Not Default To Editing Upstream Templates
-
-Local AI should default to modifying agent files inside the user project's `.cursor/agents/`. Discuss upstream template source (`packages/cli/src/templates/cursor/agents/`) only when the user explicitly wants to contribute the change back to Pactile.
+# Agent responsibilities
+
+The main Codex task owns planning, integration, verification, and final acceptance. Pactile does not install Codex subagent role files or dispatch Codex subagents.
+
+Independent Codex desktop tasks use App native tools with `pactile codex prepare|receipt|status` request and receipt records. The Node CLI cannot invoke those native tools itself. Record objective, task identity, and evidence; do not treat a message as acceptance.
+
+Use `.pactile/spec/` for project rules and `AGENTS.md` for concise managed entry instructions. Do not create agent files in a legacy host directory.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/hooks-and-settings.md

@@ -1,59 +1,7 @@
-# Hooks And Settings
-
-Hooks/settings are the entry layer that connects Cursor to Pactile. They decide which scripts run on which Cursor events.
-
-## Settings Responsibilities
-
-`.cursor/hooks.json` registers:
-
-- session-start hook: injects a Pactile overview when a new session starts or context resets (note the Cursor `additional_context` bug #158452 — see `.pactile/framework/cursor-context-injection-guide.md`).
-- workflow-state hook: parses `[workflow-state:STATUS]` blocks from `.pactile/workflow.md` and emits the body matching the selected task `status` on each user input. Parser-only; the script does not embed fallback content.
-- sub-agent context hook: injects task context when implementation/check/research agents start.
-- shell/session bridge: lets shell commands see the same Pactile session identity.
-
-> Pactile previously shipped settings/config files for many platforms (`.claude/settings.json`, `.codex/hooks.json`, `.gemini/settings.json`, etc.). The project has converged on **Cursor-only**. New Pactile features ship into `.cursor/hooks.json` + `.cursor/hooks/`.
-
-Whether legacy settings/config files exist in a project depends on which historical `pactile init --<platform>` flags the user previously ran; `pactile update` preserves them.
-
-| Platform | settings/config |
-| --- | --- |
-| Cursor | `.cursor/hooks.json` |
-
-## Hook Script Types
-
-| Script | Purpose |
-| --- | --- |
-| `session-start.py` | Generates session-start context. |
-| `inject-workflow-state.py` | Parses `[workflow-state:STATUS]` blocks in `.pactile/workflow.md` and emits the body matching the selected task status. Falls back to `Refer to workflow.md for current step.` when no matching block exists. |
-| `inject-subagent-context.py` | Injects PRD, JSONL context, and related spec/research into sub-agents. |
-| `inject-shell-session-context.py` | Lets shell commands inherit Pactile session identity. |
-| `rename-session-for-task.py` | After successful `task.py select` / `start-execution --approved`, prompts main-session rename to task directory name (best-effort `rename_chat`). |
-
-Cursor exposes sessionStart, preToolUse on Task/Subagent, beforeShellExecution, afterShellExecution, and stop events. Confirm against the current Cursor release before wiring a new event name; the available event surface has evolved over time and historical platform documentation may be stale.
-
-## Local Change Scenarios
-
-| User need | Edit location |
-| --- | --- |
-| AI should see more/less context in a new session | `.cursor/hooks.json` → `session-start` hook (or `.cursor/rules/*.mdc` for content the model must see every turn — see `.pactile/framework/cursor-context-injection-guide.md`). |
-| Per-turn hint policy should change | `[workflow-state:STATUS]` block in `.pactile/workflow.md`. The hook parses workflow.md verbatim — no script edit required. |
-| Sub-agent cannot read PRD/spec | `inject-subagent-context.py` hook or agent prelude in `.cursor/agents/*.md`. |
-| `task.py selected` in shell has no selected task | `inject-shell-session-context.py` hook or environment-variable configuration. |
-| Disable an automatic injection | The corresponding hook registration in `.cursor/hooks.json`. |
-
-## Modification Principles
-
-1. **Settings wire things up; hooks define behavior**. If only the hook changes, Cursor may never call it. If only settings change, behavior may not change.
-2. **Confirm Cursor event names first**. Cursor's hook event surface has changed between releases; what an older guide calls `UserPromptSubmit` may now be modeled by `beforeSubmitPrompt` instead.
-3. **Hooks read local `.pactile/`, not upstream source**. `.pactile/scripts/` and `.pactile/workflow.md` in the user project are the default targets.
-4. **Errors must be visible**. Hook failures should tell the user what was not injected instead of silently leaving the AI without context.
-
-## Troubleshooting Path
-
-If the user says "AI did not read Pactile state":
-
-1. Check whether `.cursor/hooks.json` registers the hook.
-2. Check whether the hook file exists under `.cursor/hooks/`.
-3. Manually run the `.pactile/scripts/get_context.py` or `task.py selected --source` command that the hook depends on.
-4. Check whether selected task state exists in `.pactile/.runtime/sessions/`.
-5. Check whether the Cursor shell passes session identity.
+# Hooks and settings
+
+A Pactile project may include a native Codex project binding when the host reports it is ready and the projection plan includes a validated fragment. Do not infer active delivery from a file's presence; verify the host's observed behavior.
+
+Canonical task state lives in `.pactile/`. Check the ownership ledger and current project files before changing any hook or setting. Keep credentials and personal host configuration outside product templates.
+
+The active install path does not write `.cursor/hooks.json` or Cursor hook scripts. Older files remain available for explicit, reviewed legacy cleanup.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/overview.md

@@ -1,45 +1,5 @@
-# Platform Files Overview
-
-Pactile connects the same local architecture to **Cursor**. `.pactile/` stores the shared runtime; `.cursor/` stores adapter files that define how Cursor enters Pactile.
-
-When a local AI modifies Pactile, it should distinguish two file categories first:
-
-- **Shared files**: `.pactile/workflow.md`, `.pactile/tasks/`, `.pactile/spec/`, `.pactile/scripts/`.
-- **Platform files**: `.cursor/` (settings, hooks, agents, skills, commands, rules).
-
-Platform files do not store business state. They let Cursor read Pactile state, call Pactile scripts, and load Pactile skills/agents/hooks.
-
-> **Historical note**: Pactile previously shipped adapter directories for many AI tools (`.claude/`, `.codex/`, `.opencode/`, etc.). The project has converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`pactile update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
-
-## Platform File Categories (Cursor)
-
-| Category | Common paths | Purpose |
-| --- | --- | --- |
-| settings/config | `.cursor/hooks.json` | Register hooks and platform behavior. |
-| hooks | `.cursor/hooks/` | Inject context at session start, pre-tool-use on Task/Subagent, before-shell-execution, and stop events. |
-| rules | `.cursor/rules/*.mdc` (`alwaysApply: true`) | Per-turn policy prepended before every prompt (e.g. Request Triage, retrieval routing). See `.pactile/framework/cursor-context-injection-guide.md` for the channel-reliability matrix. |
-| agents | `.cursor/agents/` | Define `pactile-research`, `pactile-implement`, and `pactile-check` for Task / Agent-session dispatch. |
-| skills | `.cursor/skills/` | Capability descriptions that auto-trigger or can be read on demand. |
-| commands | `.cursor/commands/` | User-invocable `/slash` entry points (e.g. `pactile-continue`, `record-session`). |
-
-## Cursor Integration Mode
-
-Cursor combines three integration styles:
-
-1. **Hook / Extension Driven** — `.cursor/hooks.json` + `.cursor/hooks/` fire on sessionStart, pre-tool-use on Task/Subagent, beforeShellExecution, and stop. Common capabilities: session-start Task Dashboard + Phase Index injection (note the `additional_context` Cursor bug #158452 — use `.cursor/rules` or `AGENTS.md` for must-always-be-visible content), PRD/jsonl injection when sub-agents start, shell commands inheriting session identity.
-2. **Agent Prelude / Pull-Based** — `.cursor/agents/*.md` instruct each custom Task subagent to read the selected task, PRD, and JSONL context after startup (the `<!-- pactile-hook-injected -->` marker confirms injected context).
-3. **Main-Session Workflow** — `.cursor/commands/*.md` and `.cursor/skills/*.md` guide the main-session AI to read files, run scripts, and move tasks forward; `.cursor/rules/*.mdc` enforce per-turn policy.
-
-To change "when the AI knows what," inspect `.cursor/hooks.json` and `.cursor/rules/` first. To change how sub-agents load context, inspect `.cursor/agents/`. To change user-invocable entry points, inspect `.cursor/commands/` and `.cursor/skills/`.
-
-## Local Modification Order
-
-When the user asks to customize behavior:
-
-1. Read `.pactile/workflow.md` to confirm the shared flow.
-2. Read `.cursor/hooks.json` to see which hooks are registered.
-3. Read the relevant `.cursor/agents/*.md`, `.cursor/skills/*/SKILL.md`, `.cursor/commands/*.md`, and `.cursor/rules/*.mdc`.
-4. Modify the local file closest to the user's need.
-5. If the change affects the shared flow, synchronize `.pactile/workflow.md` or `.pactile/spec/`.
-
-Do not modify only platform files and forget the shared workflow. Do not modify only `.pactile/workflow.md` and forget that platform entry points may still contain old descriptions.
+# Codex project files
+
+Pactile stores canonical workflow, tasks, and runtime state in `.pactile/`. The active adapter projects managed instructions into `AGENTS.md` and shared Skills into `.agents/skills/`. Optional native Codex configuration is projected only when the host reports support and a reviewed plan supplies its binding.
+
+Inspect the project's ownership ledger before changing a generated file. Existing user content is not a template to overwrite. Older `.cursor/` files are legacy installation data; new Pactile runs do not create or refresh them.

package/dist/templates/common/bundled-skills/pactile-meta/references/platform-files/platform-map.md

@@ -1,45 +1,9 @@
-# Platform File Map
-
-This page lists Pactile file locations in a user project on **Cursor**.
-
-Pactile originally supported multiple AI platforms (Claude Code, Codex, OpenCode, Kilo, Kiro, Gemini, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, Factory Droid, Pi Agent). The project has since converged on **Cursor-only**. Legacy adapter directories may still exist in upgraded projects (`pactile update` preserves user files), but new framework/runtime behavior targets Cursor exclusively.
-
-## Matrix
-
-| Platform | CLI flag | Main directory | Skill directory | Agent directory | Hooks/extensions |
-| --- | --- | --- | --- | --- | --- |
-| Cursor | `--cursor` | `.cursor/` | `.cursor/skills/` | `.cursor/agents/` | `.cursor/hooks.json` + `.cursor/hooks/` |
-
-## Capability Reference (Cursor)
-
-- **Skills** auto-trigger via the workflow matcher and can be read on demand. They live in `.cursor/skills/`.
-- **Agents** (`pactile-research`, `pactile-implement`, `pactile-check`) live in `.cursor/agents/` and are dispatched via the Task tool or opened as Agent sessions / Skill forms depending on the entry point (see `cursor-subagent-policy.md.txt`).
-- **Commands** (e.g. `record-session`, `pactile-continue`) live in `.cursor/commands/` and are user-invocable via `/slash`.
-- **Hooks** (session start, pre-tool-use on Task/Subagent, before-shell-execution, stop) are registered in `.cursor/hooks.json` and their handler scripts live in `.cursor/hooks/`.
-- **Project rules** (always-applied policy) live in `.cursor/rules/*.mdc`.
-
-## Decision Rules When Modifying Platform Files
-
-1. User specified a platform other than Cursor: treat as a legacy adapter inspection — preserve existing files but do not extend new behavior there.
-2. User says "all platforms should do this": in Cursor-only world this is equivalent to "modify the Cursor path"; also mirror any dogfooded copy under `.cursor/` in `packages/cli/src/templates/cursor/` if applicable.
-3. User only says "my AI": inspect which directories actually exist in the project; on a fresh `pactile init` only `.cursor/` and `.pactile/` are created.
-4. User wants project rules: prefer `.pactile/spec/` or a project-local skill under `.cursor/skills/`.
-5. User wants Pactile behavior: edit `.pactile/workflow.md` plus `.cursor/hooks.json` / `.cursor/agents/` / `.cursor/skills/` / `.cursor/commands/`.
-
-## When Paths Differ
-
-Cursor's layout can change between versions, and user projects may already be customized. If this table disagrees with local files, use the actual settings/config in the user project as authoritative:
-
-- Check the hook that `.cursor/hooks.json` registers.
-- Check the script that a command/agent points to.
-- Judge behavior by the read rules currently written in the agent file.
-
-Do not delete a custom file just because it is not listed in this path table.
-
-## Legacy Adapter Handling
-
-If a user project still contains legacy platform directories (e.g. `.claude/`, `.codex/`, `.opencode/`):
-
-- `pactile update` preserves them; do not delete on sight.
-- If the user asks to clean them up, suggest removing the unused platform directories after confirming they are not shared with another tool.
-- Do not register new hooks/agents/skills/commands under legacy platform directories. New Pactile features ship to `.cursor/` only.
+# Active host map
+
+| Host | Init flag | Managed project files |
+| --- | --- | --- |
+| Codex desktop | `--codex` | `AGENTS.md`, `.agents/skills/`, and optional native project configuration |
+
+Pactile does not install a Cursor adapter. `pactile detach cursor --dry-run` previews cleanup of an older installation.
+
+Check actual files and `pactile capability-smoke --json` before assuming a native hook, MCP server, or plugin is active. `pactile codex` prepares native desktop task requests and records host-reported receipts; project files alone do not dispatch another task.