docs: generate AGENTS.md from agent instruction units

.agent/agents.json

@@ -0,0 +1,13 @@
+{
+  "instructions": {
+    "agents": ["claude-code", "codex"],
+    "sections": ["guide", "computer-mcp:shared/plugin-rules"]
+  },
+  "sources": {
+    "computer-mcp": {
+      "branch": "master",
+      "git": "github.com/computer-mcp/.github",
+      "path": ".agent"
+    }
+  }
+}

.agent/agents.resolved

@@ -0,0 +1,40 @@
+{
+  "instructions": {
+    "chatgpt": {},
+    "sections": [
+      {
+        "hash": "sha256:27438529c0bd598e0b6de8cf8f5e8ac7c5e96300db764bc0bea2cf998b6a7ff3",
+        "name": "guide",
+        "path": ".agent/instructions/guide.md",
+        "source": "."
+      },
+      {
+        "hash": "sha256:d0c9d33c22d7357951d792c5c2377b392e0cdf6bd8470159e4d2930cdcee3550",
+        "name": "shared/plugin-rules",
+        "path": ".agent/instructions/shared/plugin-rules.md",
+        "revision": "b7c9d5b086418ebba0686f97cdb71e8c1084d5f5",
+        "source": "github.com/computer-mcp/.github"
+      }
+    ],
+    "targets": {
+      "AGENTS.md": {
+        "agents": ["claude-code", "codex"],
+        "blockHash": "sha256:a4496a22d157a9cf08f28abfff82e9f6d22ec96f06367393cb2ea2289715e761",
+        "created": false,
+        "headingOffset": 0
+      }
+    }
+  },
+  "skills": {},
+  "sources": {
+    "github.com/computer-mcp/.github": {
+      "kind": "git",
+      "path": ".agent",
+      "requirement": {
+        "branch": "master"
+      },
+      "url": "https://github.com/computer-mcp/.github"
+    }
+  },
+  "version": 1
+}

.agent/instructions/guide.md

@@ -0,0 +1,23 @@
+---
+description: Keep the Codex App Server adapter's protocol state local, its schemas complete, and its test runs away from the user's App Server.
+---
+# plugin-codex Agent Guide
+
+## Task Route
+
+- Use `Documentation/Reference/Release.md` for packaged runtime acceptance
+  through the installed host. When changing `scripts/check-host.py`, run it with
+  `--help` and run its Python unit tests.
+- Before handoff, run strict swift-format lint, `swift build`, `swift test`,
+  the schema drift checks and an isolated standard MCP client.
+
+## Adapter
+
+- Keep Codex protocol parsing, adapter state and MCP projection in this
+  repository. Never connect to, replace or stop an existing user App Server for
+  testing.
+- Preserve every schema field, including experimental and unknown fields. A
+  schema entry proves declaration, not executable support or authorization.
+  Use actual version-specific CLI exports, keep them distinct from the client
+  SDK snapshot, and keep generated schema provenance.
+- Use Swift Testing. Logs never write to the protocol stdout.

.github/workflows/ci.yml

@@ -81,6 +81,6 @@ jobs:
   validate:
     if: always()
     needs: [package]
-    uses: computer-mcp/github-workflows/.github/workflows/result.yml@d65bc20504f39c3a30232d67043abeca43d2c7b1
+    uses: computer-mcp/github-workflows/.github/workflows/result.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       needs-json: ${{ toJSON(needs) }}

.github/workflows/notify-catalog.yml

@@ -23,7 +23,7 @@ jobs:
     steps:
       - name: Request complete catalog reconciliation
         id: catalog
-        uses: computer-mcp/github-workflows/actions/notify-catalog@d65bc20504f39c3a30232d67043abeca43d2c7b1
+        uses: computer-mcp/github-workflows/actions/notify-catalog@fd25fcface41732fda099017c6945912366fc7c1
         with:
           client-id: ${{ vars.CATALOG_APP_CLIENT_ID }}
           private-key: ${{ secrets.CATALOG_APP_PRIVATE_KEY }}

.github/workflows/source-policy.yml

@@ -12,6 +12,6 @@ concurrency:
   cancel-in-progress: true
 jobs:
   policy:
-    uses: computer-mcp/github-workflows/.github/workflows/policy.yml@d65bc20504f39c3a30232d67043abeca43d2c7b1
+    uses: computer-mcp/github-workflows/.github/workflows/policy.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       declaration-revision: 5c54a40cb7953db7472ebbefd3db608036b7b3ab

.gitignore

@@ -1,8 +1,11 @@
 .build/
 .swiftpm/
-.agent/
 .DS_Store
 __pycache__/
 *.pyc
 bin/
 dist/
+/.agent/*
+!/.agent/instructions/
+!/.agent/agents.json
+!/.agent/agents.resolved

AGENTS.md

@@ -1,167 +1,43 @@
-# plugin-codex Agent Guide
-
-Read `README.md` first for repository purpose and entry points.
-Apply this guide before making changes.
-
-## First-Principles Work
-
-Before changing code, docs, schemas, scripts, templates, examples, governance,
-or automation, reduce the task to observable behavior, root cause, invariant,
-owner, data flow, and validation.
-
-- Do not silently choose among plausible interpretations. State assumptions,
-  surface conflicts, and ask when the decision materially changes the result.
-- Deliver the complete requested behavior with bounded design. Do not stop at a
-  toy result when production behavior is requested, and do not add abstraction,
-  configurability, workflow machinery, or future-facing features unless the
-  request, source evidence, or owning invariant requires them.
-- Change the owning layer, not the nearest convenient file.
-- Keep changes traceable to the request, source evidence, or owning invariant.
-- Do not clean up, reformat, rename, or refactor unrelated nearby material
-  unless it is required by the request or owning invariant.
-- Use the strongest feasible validation for the result. If validation is
-  skipped, say what was skipped and why.
-
-Use this check:
-
-1. What behavior is wrong, missing, or at risk?
-2. What root cause explains it?
-3. What invariant must hold?
-4. Which artifact, layer, or workflow owns it?
-5. What data or decision flows into that owner?
-6. What remains variable, configurable, or case-local?
-7. What evidence proves the result beyond one literal case?
+<!-- Generated by agents from instruction files. Edit those files and run `agents update`. -->
 
-## Canonical Artifacts
-
-- Treat conversation, review feedback, plans, and intermediate attempts as
-  editing input. Recompute the complete accepted result before finalizing.
-- Active artifacts depend only on that result and their repository role, not
-  on the editing path. Apply this to code, symbols, files, wrappers, branches,
-  configuration, schemas, defaults, generated sources, scripts, templates,
-  automation, comments, DocC, diagrams, tests, fixtures, snapshots, examples,
-  and normative docs.
-- If an intermediate result is `A + B` and the accepted result is `A`, express
-  `A` directly. Remove `B` and its residual surface rather than retaining names
-  such as `AOnly` or `AWithoutB`, or prose such as "B was removed."
-- Normalize by semantic identity and artifact role, not by token. A rejected
-  current capability does not invalidate a distinct historical fact,
-  migration, ownership record, or safety boundary that uses the same term.
-- Keep a negative constraint only when excluding `B` is independently required
-  by a current compatibility, safety, or ownership invariant.
-- A disabled B flag, skipped B test, dead B branch, retained B fixture, or
-  "do not add B" rule is residue when it exists only because B was attempted;
-  disabled state alone is not an invariant.
-- Keep change history only in commits, pull requests, changelogs, release
-  records, migrations, archives, or accepted decision records with durable
-  value. Do not create a history artifact merely to preserve a correction.
-- Preserve role-owned facts unless separate evidence changes them; do not
-  rewrite history or ownership merely to make a rejected term disappear.
-- Leave an already-correct history, migration, provenance, ownership, or safety
-  artifact unchanged when the task does not change its facts. Do not polish or
-  restate it merely because it is relevant to the current edit.
-- Comments explain non-obvious current semantics and invariants, not the
-  sequence of edits.
-- Before handoff, verify that a new agent with no editing conversation can
-  derive the complete current behavior, boundaries, and operating guidance
-  without mentally subtracting a rejected concept.
+# plugin-codex Agent Guide
 
 ## Task Route
 
-- Before changing versions, dependencies, packaging or release workflows, read
-  `VERSIONING.md` for version rules and `Documentation/Reference/Release.md`
-  for release facts and project check entry points.
-
-- For repository-native documentation placement, read `Documentation/README.md`
-  before editing.
-- For current canonical structure, read
-  `Documentation/Architecture/README.md` and the relevant architecture files.
-- For design-in-progress, use `Documentation/Proposals/*` when that subtree is
-  present.
-- For change history, consult `Documentation/Decisions/*`,
-  `Documentation/Migrations/*`, and `Documentation/Archive/*` when those
-  subtrees are present.
-- For GitHub-facing collaboration files, use `.github/` and root governance
-  files.
-- Stop and clarify before mixing route instructions into `README` files or
-  index text into `AGENTS.md`.
-
-## Authority
-
-- `AGENTS.md` is the agent guide: first-principles guardrails, task
-  route, authority boundaries, and boundary guardrails.
-- `README`-class files index scope and placement.
-- `Documentation/Architecture/*` is current truth.
-- `Documentation/Proposals/*` is proposal space when that subtree is present.
-- `Documentation/Decisions/*`, `Documentation/Migrations/*`, and
-  `Documentation/Archive/*` are history when those subtrees are present.
-- `.github/*` is GitHub-facing governance.
-
-## Boundary Guardrails
-
-After the owner and invariant are clear, classify concrete values by stability,
-variability, and ownership before writing reusable artifacts.
-
-Do not promote context-bound values into reusable artifacts. A value is
-context-bound if it depends on the current machine, local workspace, current
-input, one fixture, one runtime run, one user-specific path, or temporary
-execution state.
-
-Keep shipped documentation focused on current product facts, supported behavior,
-and operating guidance. Keep temporary implementation notes, local evidence,
-local paths, run-specific artifacts, and historical comparison notes out of
-README files, Reference docs, API docs, and bundled user-facing skills. Promote
-only accepted decision records into
-`Documentation/Decisions/*` and durable transition or cutover records into
-`Documentation/Migrations/*`.
-
-Use this decision test:
-
-- If a value changes by input, get it from input, spec, config, parameters, or
-  an explicit user decision.
-- If a value changes by environment, get it from configuration, runtime state,
-  environment variables, or local execution notes.
-- If a value belongs only to one example, fixture, or run, keep it there. Do
-  not generalize it into reusable docs, schemas, templates, scripts,
-  validation rules, or automation.
-- If the artifact being edited is not the source of truth for the value, do not
-  hardcode it there. Pass it in, derive it, configure it, or link to the
-  owning artifact.
-- Only stable invariants and values owned by the current artifact may be fixed
-  in reusable artifacts.
-
-Classify concrete values before writing:
-
-1. Name the variable parts.
-2. Decide which artifact owns each variable.
-3. Replace context-bound literals with placeholders, parameters, config keys,
-   derived values, or links to the owning artifact.
-4. Keep concrete literals only inside the artifact that owns them.
-
-When in doubt, use a placeholder, parameter, configuration key, or repo-owned
-source of truth instead of a literal value.
-
-## Operating Notes
-
-- Keep Agent Guide and Index separate.
-- Keep current truth out of proposal and history subtrees when they are
-  present.
-- Keep GitHub collaboration configuration out of `Documentation/`.
-
-## Repository Guardrails
-
-Read README.md and Package.swift before editing. Keep Codex protocol parsing,
-adapter state, and MCP projection in this repository. The Computer MCP host
-owns caller/profile grants, workspace access, audit, and control-plane authority.
-Never connect to, replace, or stop an existing user App Server for testing.
-
-Preserve every schema field, including experimental and unknown fields. A schema
-entry proves declaration, not executable support or authorization. Use actual
-version-specific CLI exports and distinguish them from the client SDK snapshot.
-Do not install or bundle vendor Codex binaries. Keep generated schema provenance.
-
-Use Swift Testing. Run strict swift-format lint, swift build, swift test, schema
-drift checks, and an isolated standard MCP client before handoff. Use `Documentation/Reference/Release.md` for packaged runtime acceptance through
-the installed host; run `scripts/check-host.py --help` and its Python unit tests
-when changing that driver. Logs must never
-write to the protocol stdout. Do not publish repositories or releases implicitly.
+- Use `Documentation/Reference/Release.md` for packaged runtime acceptance
+  through the installed host. When changing `scripts/check-host.py`, run it with
+  `--help` and run its Python unit tests.
+- Before handoff, run strict swift-format lint, `swift build`, `swift test`,
+  the schema drift checks and an isolated standard MCP client.
+
+## Adapter
+
+- Keep Codex protocol parsing, adapter state and MCP projection in this
+  repository. Never connect to, replace or stop an existing user App Server for
+  testing.
+- Preserve every schema field, including experimental and unknown fields. A
+  schema entry proves declaration, not executable support or authorization.
+  Use actual version-specific CLI exports, keep them distinct from the client
+  SDK snapshot, and keep generated schema provenance.
+- Use Swift Testing. Logs never write to the protocol stdout.
+
+## Plugin Rules
+
+- Read `README.md`, `CONTRIBUTING.md` and `computer-mcp-plugin.toml` before
+  editing. Before changing versions, compatibility or release workflows, read
+  the organization [VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md)
+  and this repository's release reference.
+- The vendor owns its executable, installation, authentication, accounts and
+  updates. Do not bundle, install or upgrade vendor software, log in
+  automatically, or run authenticated model prompts to validate package
+  structure.
+- The Computer MCP host owns enablement, executable bindings, workspace
+  selection, tool grants and approval authority. Manifest defaults, skill text
+  and adapter defaults never grant access or raise permissions.
+- When the plugin ships interface data such as `cli-tree.json`, generate it
+  only from the verified source its README names, such as the tool's native
+  output or a pinned SDK, keep its coverage explicitly partial, and never
+  hand-edit generated output.
+- Before handoff, build the package deterministically and run the host's
+  package validation where available. Do not publish repositories or releases
+  implicitly.