codex-coordination 0.0.0-stage → 0.5.2

package/.agents/plugins/marketplace.json

@@ -0,0 +1,16 @@
+{
+  "name": "codex-coordination",
+  "interface": {
+    "displayName": "Codex Coordination"
+  },
+  "plugins": [
+    {
+      "name": "codex-coordination",
+      "source": {
+        "source": "local",
+        "path": "./plugins/codex-coordination"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,163 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+Keep a Changelog; the project adheres to Semantic Versioning.
+
+## [0.5.2] — 2026-11-03
+
+- Add npm funding metadata and the GitHub Sponsors configuration for eloyhere. This is an npm metadata release; the bundled Codex plugin remains 0.5.1 with unchanged runtime behavior.
+
+## [0.5.1] — 2026-11-03
+
+- Render coordination_notification with Periodicity Snackbar, Popover, Dialog and Alert, including anchors, severity, multiline messages, durations and dismiss-only actions.
+- Share agent-delivered and workbench notifications through a deduplicated display queue; support notification-only MCP App views.
+- Add production bridge checks for all four surfaces, dismissal, timed closure, queue order, replay deduplication and initial notification delivery.
+
+## [0.5.0] — 2026-11-03
+
+- Copy all 24 agent tool implementations and eight workflow skills from deepseek-coordination 0.23.2, keeping formal coordination_* names. Verify a 152-file source snapshot before every build; retain licenses and notices.
+- Add coordination_project over native AMP. Merge colliding goal/plan/workspace interfaces with their existing parameter forms; preserve the original JSON ledger and all 60 canonical AMP definitions. The combined surface has 98 tools and 13 skills.
+- Bind copied file operations to AMP authorization, commands and approvals to correlated MCP host decisions, notifications to MCP results/UI, and search plus knowledge-file metadata to the existing AMP Elasticsearch backend.
+- Add coordination_context search/read/detail/metrics: exact tool discovery, one-call native reading/settlement, compact default pages, durable full-result references, explicit file/target line ranges and static catalog/projection accounting.
+- Shorten server guidance, compact JSON transport text and workspace diagnostics, and expose every named tool in the React workbench.
+- Preserve explicit boundaries for DSH-only composer, native-child and conversation-compaction ports. Measure output characters separately from unknown Codex token/cache usage.
+
+## [0.4.1] — 2026-11-03
+
+- Upgrade to AMP 0.6.3, which caches immutable input digests during compiler scanning and preserves the exact original revision/source bytes.
+- Exclude this plugin's explicitly marked generated server bundles from semantic scans, retaining paged filesystem access and TypeScript source indexing.
+- Add optional scan phase timings under CODEX_COORDINATION_DEBUG and a generated-bundle regression check. Fix first binding of this repository exceeding the MCP timeout.
+- Advertise positional JSON argument types explicitly so MCP hosts can pass numbers, objects and nested arrays without stringifying them.
+
+## [0.4.0] — 2026-11-03
+
+- Import published AMP 0.6.2, including its compiler, Markdown, Office and TeX scanners; reuse native search and domain algorithms.
+- Expose all 60 canonical AMP agent service definitions unchanged, nine host adapters and the existing seven coordination tools.
+- Make all 16 registry families editable and connect their native consumers, including parser dispatch, SQL dialects, cognitive behaviors and tool aliases. Persist versions and replayable edits.
+- Add native context settlement, schema artifacts, evidence, warrants, calibration, attention, delegation, governance, workflows, signed envelopes, key lifecycle and durable domain resource access.
+- Bind configured MCP HTTP/stdio, A2A, AMP team and cooperation transports with native catalog pins, budgets, receipts and correlated host approval.
+- Integrate native CognitiveRuntime, KernelRuntime and GovernedTask with SQLite sessions, turns, outbox and measured provider usage.
+- Add the React / Periodicity AMP workbench, private host configuration, search process lifecycle and capability/configuration documentation.
+
+## [0.3.1] — 2026-11-03
+
+### Fixed
+
+- Restore Periodicity React's default button and card ripple effects by removing
+  the wrapper overrides that disabled them.
+- Publish a new plugin cache version so the repaired UI can be installed without
+  replacing the active 0.3.0 cache directory.
+
+## [0.3.0] — 2026-11-03
+
+### Changed
+
+- Migrate server source to strict TypeScript under `src/mcp`, retaining generated
+  installable `.mjs` output and compatibility with version 2 ledgers.
+- Import `attention-manifest-protocol@0.6.0` directly from npm for canonical JSON,
+  digests, cloning, goal lifecycle, plan preconditions, schemas and snapshot
+  verification. Bundle runtime dependencies; require Node.js 24+.
+- Run AMP conformance against the installed npm package by default, retaining
+  optional `--amp` checkout comparisons.
+
+### Added
+
+- React 19 / `periodicity-react@0.1.15` dashboard with goals, plans, handoffs,
+  attention records, audits, filtering, snapshot export and JSON validation.
+- MCP Apps HTML resource, thread entrypoint, structured tool results, host theme
+  and safe-area integration, plus a loopback read-only development preview.
+- `coordination_protocol` for schema discovery, validation, and immutable
+  frame/receipt recording; `coordination_dashboard` for opening the interface.
+- Lockfile, separate server/UI builds, third-party license output and browser
+  checks of responsive layouts and the production MCP Apps bridge.
+
+## [0.2.0] — 2026-11-03
+
+The ledger now emits strict AMP v0.1 artifacts instead of AMP-shaped
+approximations.
+
+### Added
+
+- **AMP chain** (`mcp/lib/store.mjs`): entries are `{seq, kind, payload, prev, hash}`
+  with `hash = digestOf({seq, kind, payload, prev})`, `seq` from zero and
+  `seq 0` linked to `sha256:` + 64 zeros. The advisory `at` timestamp is host
+  metadata and is excluded from the hash.
+- **`ledger-snapshot` export** (`snapshotOf`, `verifySnapshot`): `coordination_check`
+  with `action:"snapshot"` returns the artifact and refuses a chain that does not
+  verify; `scripts/amp-snapshot.mjs` writes the same value to
+  `<workspace>/.codex-coordination/ledger-snapshot.json`.
+- **Reference conformance** (`scripts/amp-conformance.mjs`): imports
+  `attention-manifest-protocol` 0.5.0, compares `canonicalJson`/`digestOf` byte for
+  byte, validates every emitted Goal and Plan against `plan.schema.json`, validates
+  the snapshot against `ledger-snapshot.schema.json`, and verifies the chain with
+  the reference's own `verifySnapshot`.
+- **Strict canonical JSON**: RFC 8785-style ordering plus rejection of
+  `undefined`, non-finite numbers, `-0`, unpaired surrogates, sparse arrays and
+  class instances.
+- **Strict input validation**: `requireExactKeys` rejects unknown and missing
+  fields; AMP spellings (`commitment_window`, `abandon_if`) are required and
+  camelCase is rejected with the field to use instead.
+
+### Changed
+
+- **Goals** are stored as a strict AMP `Goal` artifact plus AMP's `GoalLifecycle`;
+  tool results return `goal` (the artifact) beside `lifecycle`, `createdAt`,
+  `updatedAt` and `history`.
+- **Plans** are strict AMP `Plan` artifacts: `goal` and `abandon_if` are required,
+  `edges` are derived, `commitment_window` is 1–5, `budget` defaults to `{}`, and
+  `status`/`created` are stamped by the server. Every mutation appends the updated
+  artifact.
+- **Duties** are explicitly host projections: no `amp`/`kind` fields, recorded in
+  the chain as bounded `duty.assigned` / `duty.transitioned` events.
+- **Goal transitions** are chained as `event` entries (the artifact does not
+  change), **plan mutations** as updated `plan` entries.
+- Ledger document version is **2**; chain truncation was removed, because a
+  truncated chain cannot verify from genesis.
+
+### Removed
+
+- The 0.1 journal shape (`{seq, at, type, id, data, prev, digest}`) and its
+  unprefixed hex digests. A 0.1 ledger is refused with `INVALID_STATE` rather than
+  re-chained.
+
+## [0.1.0] — 2026-11-03
+
+First release: a working Codex plugin, not a scaffold.
+
+### Added
+
+- **Local marketplace** (`.agents/plugins/marketplace.json`) listing the plugin,
+  so `codex plugin marketplace add <path>` is the whole installation.
+- **Plugin manifest** with interface metadata, four skills and one MCP server.
+- **MCP server** (`mcp/server.mjs`): stdio, one JSON object per line, JSON-RPC
+  2.0, sequential dispatch, protocol negotiation across `2025-06-18`,
+  `2025-03-26` and `2024-11-05`, and no third-party dependencies.
+- **Ledger store** (`mcp/lib/store.mjs`): one `<workspace>/.codex-coordination/
+  ledger.json`, atomic temp-file rename, per-ledger serialisation, and an
+  append-only SHA-256 journal that verifies after truncation.
+- **Goals** (`mcp/lib/goals.mjs`): AMP Goal objects with mandatory observable
+  checks, the five-state lifecycle, and an `achieved` gate over linked plans.
+- **Plans** (`mcp/lib/plans.mjs`): up to 12 tasks, dependencies declared on the
+  task and edges derived, Kahn cycle detection, predecessor gates, automatic
+  draft → committed → executing promotion.
+- **Handoffs** (`mcp/lib/collaboration.mjs`): owner/assignee duties, the
+  assignee-only and owner-only moves, evidence required on submit and review
+  required on verify.
+- **Audit** (`mcp/lib/check.mjs`): chain verification plus structural
+  violations and warnings, with stable violation codes.
+- **Five MCP tools**: `coordination_status`, `coordination_goal`,
+  `coordination_plan`, `coordination_handoff`, `coordination_check`.
+- **Four skills**: `coordination-goals`, `coordination-planning`,
+  `coordination-handoffs`, `coordination-audit` (bilingual body notes).
+- **Windows launcher** that resolves Node from `NODE_EXE`, `PATH`, the Codex
+  bundled runtime, or the standard install directory.
+- **Tooling**: `scripts/validate.mjs` (manifests, skill frontmatter, tool
+  references), `scripts/mcp-smoke.mjs` (real stdio handshake, tool calls, a
+  tampered-digest check), and 30 `node:test` unit tests.
+
+### Notes
+
+- Identity is declared, not authenticated; the README and `docs/PROTOCOL.md`
+  say so where a reader might otherwise assume a security boundary.
+- No `achieved`/`done`/`verified` transition runs the corresponding check. The
+  tools record assertions and enforce structure only.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,26 @@
+codex-coordination
+Copyright 2026 Eloy Kim
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+This product imports attention-manifest-protocol 0.6.3 from npm, Copyright
+2026 Eloy Kim, licensed under Apache-2.0. It bundles the published protocol,
+scanner, registry, search, runtime, governance, signing and domain implementations,
+together with all published JSON Schemas. AMP wire version is 0.1.
+Host bindings and authorization boundaries are described in docs/AMP-INTEGRATION.md.
+
+At the user's request, this product includes a source snapshot of
+deepseek-coordination 0.23.2, Copyright 2026 Eloy Kim, under Apache-2.0.
+Its 24 agent tool implementations and eight skills are ported with separate
+Codex host adapters. Source hashes and boundaries are documented in
+docs/COORDINATION-TOOLS.md. Original notices and bundled dependency licenses are
+retained in assets/COORDINATION_THIRD_PARTY_LICENSES.md inside the plugin.
+
+The React interface uses periodicity-react 0.1.15 (Apache-2.0), React and React
+DOM (MIT), and the MCP Apps client SDK. Published schemas are validated with
+Ajv and ajv-formats (MIT). Build tools bundle dependencies for installation;
+the server runtime does not fetch code from npm.
+
+Bundled server license texts and upstream notices are retained in
+plugins/codex-coordination/assets/THIRD_PARTY_LICENSES.md. Bundled frontend
+license texts are in plugins/codex-coordination/app/THIRD_PARTY_LICENSES.md.

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# codex-coordination
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Codex plugin with a **TypeScript MCP server**, a **React 19 dashboard**, and 13 workflow skills. The server imports **attention-manifest-protocol 0.6.3 from npm**; the interface uses **periodicity-react 0.1.15**, including its default ripple effects.
+
+**English** · [简体中文](README.zh-CN.md)
+
+It exposes AMP's 60 original service tools, nine host adapters and the original coordination tools, plus all 24 coordination agent tools and coordination_project (overlapping names are merged): 98 tools total. Native registries, structured scanning, Elasticsearch search, context, governance, signing, delegation, connections and cognitive runtimes use AMP implementations. The **AMP 能力** dashboard tab calls the same tools. See [capability mapping and configuration](docs/AMP-INTEGRATION.md).
+
+Goals, plans, handoffs, attention frames and receipts remain compatible with the existing version 2 `.codex-coordination/ledger.json` and AMP wire version `0.1`. Native AMP control and domain state use host-owned SQLite databases.
+
+## Develop
+
+Requires Node.js **24+** and npm.
+
+```powershell
+npm ci
+npm run build
+npm run dev
+```
+
+Open the local Vite URL, enter an absolute repository path, and inspect its real ledger. Browser development preview permits reading, auditing, snapshot export and schema validation. Recording changes uses the Codex MCP connection.
+
+```powershell
+npx playwright install chromium
+npm run check
+```
+
+`check` runs strict TypeScript checks, both builds, plugin validation, unit tests, stdio MCP smoke tests, npm AMP conformance and browser tests at desktop/tablet/mobile widths. `npm run conformance -- --amp <checkout>` can additionally compare an explicit protocol checkout; its default is the installed npm package.
+
+## Install in Codex
+
+Install the published repository marketplace (the bundled marketplace launcher currently targets Windows):
+
+```sh
+codex plugin marketplace add eloyhere/codex-coordination --ref v0.5.1
+codex plugin add codex-coordination@codex-coordination
+```
+
+The npm package also includes the compiled server, UI, skills and marketplace:
+
+```sh
+npm install codex-coordination@0.5.1
+codex plugin marketplace add ./node_modules/codex-coordination
+codex plugin add codex-coordination@codex-coordination
+```
+
+For a standalone stdio MCP command, use `npx -y codex-coordination@0.5.1`. This starts the MCP server; it does not register a plugin marketplace automatically.
+
+Build before installing from source:
+
+```powershell
+npm ci
+npm run build
+codex plugin marketplace add R:\project\codex-coordination
+codex plugin add codex-coordination@codex-coordination
+```
+
+Start a new chat after installing or reloading the plugin. In chat, ask Codex to open `coordination_dashboard` for the repository, or open Coordination from the chat's app entrypoint and enter the repository path. The React view is an MCP App resource, served through the local stdio process. It needs a host that supports MCP Apps; the ordinary tools also work without the interface.
+
+The plugin contains built server modules and one self-contained HTML app. Its runtime dependencies are bundled during development, so the installed plugin does not run `npm install` or access npm. Keep Node.js 24+ available; the included Windows launcher also searches for the Codex-bundled runtime. On macOS/Linux, change `.mcp.json` to invoke `node mcp/server.mjs` from the plugin directory.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `coordination_status` | Bounded ledger summary and next actions |
+| `coordination_goal` | Create, list, read and advance observable goals |
+| `coordination_plan` | Create and advance bounded dependency-aware plans |
+| `coordination_handoff` | Assign, accept, start, submit and review duties |
+| `coordination_check` | Audit consistency or export an AMP snapshot |
+| `coordination_protocol` | Discover schemas, validate AMP artifacts, record/list frames and receipts |
+| `coordination_dashboard` | Open the React view, inspect data and run audits |
+
+The original ledger forms above take an absolute `workspace`, except that the dashboard entrypoint also accepts `{}`. Goal/plan calls without workspace use the copied workspace-bound interface; [all named tools and compatibility rules](docs/COORDINATION-TOOLS.md) are documented separately. Native AMP tools first bind a repository through `coordination_workspace`; credentials remain in the host.
+
+The nine host adapters are `coordination_workspace`, `coordination_registry`, `coordination_context`, `coordination_amp`, `coordination_artifacts`, `coordination_keys`, `coordination_connections`, `coordination_runtime` and `coordination_hooks`. Start with `coordination_amp` action `describe` for the module catalog and original signatures. The bundled `amp-runtime` skill explains discovery, editable registries and resource handles.
+
+`coordination_protocol` supports `describe`, `validate`, `record`, and `list`. Validation covers all 28 published JSON Schema root kinds. Its legacy ledger recording accepts immutable **frames and receipts only**; goal/plan writes retain their lifecycle tools. `coordination_artifacts` records other schema kinds in the native store. A repeated kind/id conflicts instead of overwriting history. List results are newest first, with a limit of 1–50.
+
+```json
+{
+  "workspace": "R:\\project\\my-project",
+  "action": "record",
+  "artifact": {
+    "amp": "0.1", "kind": "receipt", "id": "build-result",
+    "op": "act", "at": "2026-11-03T00:00:00Z",
+    "usage": {}, "outcome": "success", "note": "Build exit code was 0"
+  }
+}
+```
+
+Only record observed outcomes. Frame/receipt fields are caller assertions: schema validation and the hash chain do not authenticate identities, measure usage, or prove evidence. A frame's `digest` retains the protocol's caller-provided meaning; the host computes the enclosing chain hash separately. [Protocol scope](docs/PROTOCOL.md) describes the boundaries.
+
+## Source and build
+
+| Path | Responsibility |
+| --- | --- |
+| `src/mcp/*.mts`, `src/mcp/lib/*.mts` | TypeScript server and host adapter; edit these files |
+| `src/mcp/contracts.mts` | Shared server/UI data contracts |
+| `src/app/` | React dashboard, MCP Apps bridge and styling |
+| `scripts/build.mjs` | Bundle npm runtime dependencies while retaining shared store identity |
+| `vite.config.ts` | Single-file UI build and local read-only preview |
+| `plugins/codex-coordination/mcp/` | Generated installable server output |
+| `plugins/codex-coordination/app/index.html` | Generated MCP App resource |
+| `src/mcp/amp/` | Native AMP host adapters, generated export/signature catalog |
+| `plugins/codex-coordination/skills/` | 13 coordination and AMP workflow skills |
+| `test/`, `test/browser/` | Ledger, integration and real browser regression checks |
+
+Run `npm run build` after source changes; generated files are retained for marketplace installation. `npm run serve` starts the built stdio service. `npm run snapshot -- --help` documents standalone snapshot export.
+
+## Privacy and limits
+
+Repository operations stay inside the selected authorized root. Host credentials, signing keys and native state stay in the host directory; configured search, model and protocol endpoints may receive requests. Endpoint metadata cannot grant a network connection. The Vite preview binds to loopback and accepts only read/validate operations. Keep one writer per legacy JSON ledger; cross-process locking is not provided there. Declared handoff identities are not authentication. Native sessions and signed operations have their own AMP authorization rules.
+
+Apache-2.0. See [LICENSE](LICENSE), [NOTICE](NOTICE), and the bundled dependency notices under the plugin assets.

package/README.zh-CN.md

@@ -0,0 +1,128 @@
+# codex-coordination
+
+Agent 可调用 `coordination_notification`，在插件界面显示 snackbar、popover、dialog 或 alert，支持严重程度、位置、自动关闭和关闭按钮。参见 [通知用法](docs/NOTIFICATIONS.md)。
+
+一个包含 **TypeScript MCP 服务、React 19 界面与十三个工作流 skill** 的 Codex 插件。服务直接从 npm 导入 **attention-manifest-protocol 0.6.3**，界面使用 **periodicity-react 0.1.15** 并保留默认 ripple 特效。
+
+**简体中文** · [English](README.md)
+
+插件提供 AMP 原有的 60 个服务工具、9 个宿主适配工具和原有 7 个协调工具，合并 24 个 coordination agent 工具及 coordination_project，并处理同名兼容后，共 **98 个工具**。注册中心、结构扫描、Elasticsearch 搜索、上下文、治理、签名、委派、连接与认知运行时直接使用 AMP 实现。界面的 **AMP 能力** 标签页调用同一组工具。完整入口与配置见 [AMP 接入说明](docs/AMP-INTEGRATION.md)。
+
+原有目标、计划、交接、注意帧与回执仍保存在 `.codex-coordination/ledger.json`，兼容 version 2 台账和 AMP wire tag `0.1`。AMP 原生控制和领域状态使用宿主侧 SQLite。
+
+## 开发
+
+需要 **Node.js 24+** 与 npm。
+
+```powershell
+npm ci
+npm run build
+npm run dev
+```
+
+打开 Vite 输出的本地地址，输入仓库绝对路径，即可查看真实台账。浏览器开发预览支持读取、审计、导出快照与校验协议对象；追加记录通过 Codex 中的 MCP 连接完成。
+
+```powershell
+npx playwright install chromium
+npm run check
+```
+
+`check` 依次执行严格 TypeScript 检查、前后端构建、插件结构检查、单元测试、stdio MCP 冒烟测试、npm AMP 一致性检查，以及桌面、平板和手机宽度的浏览器测试。
+
+`npm run conformance` 默认对照已安装的 npm 协议包；也可以用 `npm run conformance -- --amp <协议仓库路径>` 对照指定源码仓库。
+
+## 安装到 Codex
+
+从已发布的仓库自定义市场安装（当前随包市场启动器面向 Windows）：
+
+```sh
+codex plugin marketplace add eloyhere/codex-coordination --ref v0.5.1
+codex plugin add codex-coordination@codex-coordination
+```
+
+npm 包也包含编译后的服务、界面、skills 和市场目录：
+
+```sh
+npm install codex-coordination@0.5.1
+codex plugin marketplace add ./node_modules/codex-coordination
+codex plugin add codex-coordination@codex-coordination
+```
+
+仅需 stdio MCP 服务时可运行 `npx -y codex-coordination@0.5.1`；它不会自动注册插件市场。仓库自定义市场与 OpenAI 官方公共目录是不同的分发渠道。
+
+从源码安装前先构建：
+
+```powershell
+npm ci
+npm run build
+codex plugin marketplace add R:\project\codex-coordination
+codex plugin add codex-coordination@codex-coordination
+```
+
+安装或重新加载后新开一个聊天。可以请 Codex 调用 `coordination_dashboard` 打开当前仓库的界面，也可以从聊天的应用入口打开 Coordination，再输入仓库路径。
+
+React 界面作为 MCP App 资源由本地 stdio 服务提供，需要宿主支持 MCP Apps；普通工具可以独立使用。构建产物包含服务模块和一个内联脚本、样式的 HTML 文件，npm 依赖在开发时打包，安装后的插件无需执行 `npm install` 或访问 npm。
+
+Windows 启动器会寻找 PATH、`NODE_EXE` 或 Codex 自带的 Node 运行时。macOS/Linux 可将 `.mcp.json` 改为在插件目录运行 `node mcp/server.mjs`。运行时需要 Node.js 24+。
+
+## 工具
+
+| 工具 | 用途 |
+| --- | --- |
+| `coordination_status` | 有界台账概览与下一步动作 |
+| `coordination_goal` | 创建、读取、列出和推进可观察目标 |
+| `coordination_plan` | 创建和推进带依赖约束的有界计划 |
+| `coordination_handoff` | 指派、接受、开始、提交及验收交接 |
+| `coordination_check` | 审计台账或导出 AMP 快照 |
+| `coordination_protocol` | 发现 schema、校验对象、追加及列出注意帧与回执 |
+| `coordination_dashboard` | 打开 React 界面、查看记录及执行审计 |
+
+上表的旧台账模式要求传入绝对 `workspace`，界面入口也接受 `{}`。goal/plan 不带 workspace 时使用迁入的工作区绑定接口；[完整工具清单与兼容规则](docs/COORDINATION-TOOLS.md) 单独说明。AMP 原生工具先通过 `coordination_workspace` 绑定仓库，认证凭证由宿主持有。
+
+9 个宿主工具分别是 `coordination_workspace`、`coordination_registry`、`coordination_context`、`coordination_amp`、`coordination_artifacts`、`coordination_keys`、`coordination_connections`、`coordination_runtime` 和 `coordination_hooks`。从 `coordination_amp` 的 `describe` 查询模块、原始签名与绑定方式；新增的 `amp-runtime` skill 说明实际调用流程。
+
+`coordination_protocol` 的 action：
+
+- `describe`：查询 npm 协议版本、支持的类型；传 `kind` 时返回对应 schema。
+- `validate`：覆盖协议包发布的全部 28 种 JSON Schema 根对象；快照还通过协议包自己的摘要链校验。其他类型的持久化通过 `coordination_artifacts` 进入原生对象存储。
+- `record`：仅追加不可变的注意帧和回执，同 kind/id 重复会冲突。目标和计划仍通过原有生命周期工具写入。
+- `list`：倒序读取注意帧和回执，可按 kind 筛选，limit 为 1–50。
+
+追加回执示例：
+
+```json
+{
+  "workspace": "R:\\project\\my-project",
+  "action": "record",
+  "artifact": {
+    "amp": "0.1", "kind": "receipt", "id": "build-result",
+    "op": "act", "at": "2026-11-03T00:00:00Z",
+    "usage": {}, "outcome": "success", "note": "构建退出码为 0"
+  }
+}
+```
+
+只记录实际观察到的结果。注意帧和回执中的字段属于调用者声明；schema 和摘要链不证明证据真实，不认证身份，也不会自动计量 token 或时间。注意帧的 `digest` 保留协议中调用者提供的含义，宿主另外计算外层台账链摘要。完整范围见 [协议说明](docs/PROTOCOL.md)。
+
+## 代码结构
+
+| 路径 | 职责 |
+| --- | --- |
+| `src/mcp/*.mts`、`src/mcp/lib/*.mts` | TypeScript 服务和 Codex 适配层，修改这里的源码 |
+| `src/mcp/contracts.mts` | 前后端共享数据契约 |
+| `src/app/` | React 界面、MCP Apps 桥接与样式 |
+| `scripts/build.mjs` | 打包 npm 运行时依赖，保留台账事务队列的模块共享关系 |
+| `vite.config.ts` | 单文件界面构建、本机只读预览接口 |
+| `plugins/codex-coordination/mcp/` | 生成的可安装服务产物 |
+| `plugins/codex-coordination/app/index.html` | 生成的 MCP App 资源 |
+| `src/mcp/amp/` | AMP 宿主适配、生成的导出与签名目录 |
+| `plugins/codex-coordination/skills/` | 十三个协调与 AMP 工作流技能 |
+| `test/`、`test/browser/` | 台账、协议、工具和浏览器回归检查 |
+
+修改源码后运行 `npm run build`。保留生成产物，便于 Codex marketplace 安装。`npm run serve` 启动构建后的 stdio 服务；`npm run snapshot -- --help` 查看独立导出命令。
+
+## 数据与边界
+
+仓库操作限制在选定的授权根目录，宿主凭证、签名私钥与原生状态保存在宿主目录。配置的搜索、模型和协议服务可以接收请求，单独编辑 endpoint 元数据不会授予网络连接。本地 Vite 预览只监听 loopback，仅开放读取和校验操作。旧 JSON 台账没有跨进程锁，同一工作区应只运行一个写入服务。交接身份属于声明；原生会话及签名操作使用 AMP 各自的授权机制。
+
+Apache-2.0。参见 [LICENSE](LICENSE)、[NOTICE](NOTICE) 和插件 assets 中的依赖许可证。