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:2102cd5afa3b5b18d7888c693999ec57c70e2cec04821b91de26661f1a3a862d",
+        "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:4b0e8fa9f7c91428f774f2e33266b2e48537e5670667846cc9c604d7e7dc3223",
+        "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,20 @@
+---
+description: Keep the Computer Use plugin declarative, its skill portable, and its GUI verification on disposable targets.
+---
+# plugin-computer-use Agent Guide
+
+## Plugin Boundaries
+
+- Keep this a declarative plugin that connects directly to the vendor's native
+  MCP implementation; package-owned guidance is not a proxy or runtime.
+- Keep `skills/observe-act-verify/SKILL.md` portable and independent of a
+  particular user's paths, targets, credentials or tool catalog snapshot.
+- Preserve the native AX fallback and never replay an uncertain write through
+  a second backend. Real GUI verification requires a disposable, authorized
+  target.
+
+## Validation
+
+- Build the package with `scripts/build-package.sh OUTPUT_DIRECTORY`, then
+  inspect it with the host's package validation and installation tests. Keep
+  test evidence outside the repository.

.github/workflows/ci.yml

@@ -50,6 +50,6 @@ jobs:
   validate:
     if: always()
     needs: [package, minimum-python]
-    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/release.yml

@@ -16,7 +16,7 @@ jobs:
     permissions:
       contents: write
       actions: read
-    uses: computer-mcp/github-workflows/.github/workflows/plugin-release.yml@d65bc20504f39c3a30232d67043abeca43d2c7b1
+    uses: computer-mcp/github-workflows/.github/workflows/plugin-release.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       ref: ${{ inputs.ref }}
       publish: ${{ inputs.publish }}

.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,6 +1,9 @@
 .DS_Store
-.agent/
 dist/
 *.pyc
 package-receipt.json
 __pycache__/
+/.agent/*
+!/.agent/instructions/
+!/.agent/agents.json
+!/.agent/agents.resolved

AGENTS.md

@@ -1,169 +1,40 @@
-# plugin-computer-use 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?
-
-## 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.
-
-## Task Route
-
-- Before changing versions, dependencies, packaging or release workflows, read
-  the [organization VERSIONING](https://github.com/computer-mcp/.github/blob/master/VERSIONING.md)
-  for version rules and `docs/Reference/Release.md` for release facts
-  and check entry points.
-
-- For repository-native documentation placement, read `docs/README.md`
-  before editing.
-- For current canonical structure, read
-  `docs/Architecture/README.md` and the relevant architecture files.
-- For design-in-progress, use `docs/Proposals/*` when that subtree is
-  present.
-- For change history, consult `docs/Decisions/*`,
-  `docs/Migrations/*`, and `docs/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
+<!-- Generated by agents from instruction files. Edit those files and run `agents update`. -->
 
-- `AGENTS.md` is the agent guide: first-principles guardrails, task
-  route, authority boundaries, and boundary guardrails.
-- `README`-class files index scope and placement.
-- `docs/Architecture/*` is current truth.
-- `docs/Proposals/*` is proposal space when that subtree is present.
-- `docs/Decisions/*`, `docs/Migrations/*`, and
-  `docs/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
-`docs/Decisions/*` and durable transition or cutover records into
-`docs/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 `docs/`.
-
-## Repository Guardrails
+# plugin-computer-use Agent Guide
 
-Read `README.md` and `computer-mcp-plugin.toml` before changing this package.
+## Plugin Boundaries
 
-- Keep this a declarative Computer MCP plugin. Connect directly to the vendor's
-  native MCP implementation; package-owned guidance is not a proxy or runtime.
-- The vendor owns the Computer Use client and its installation. Do not copy its
-  executable into the package or install/upgrade external dependencies.
-- Host settings own enablement, executable bindings and tool grants. Manifest
-  defaults and skill text cannot grant access.
+- Keep this a declarative plugin that connects directly to the vendor's native
+  MCP implementation; package-owned guidance is not a proxy or runtime.
 - Keep `skills/observe-act-verify/SKILL.md` portable and independent of a
   particular user's paths, targets, credentials or tool catalog snapshot.
-- Validate the package with `scripts/build-package.sh OUTPUT_DIRECTORY`, then
-  inspect it using the host's package validation and installation tests.
-- Keep test evidence outside the repository; do not publish repositories or
-  artifacts without explicit authorization.
-- Preserve native AX fallback and never replay an uncertain write through a
-  second backend. Real GUI verification requires a disposable, authorized target.
+- Preserve the native AX fallback and never replay an uncertain write through
+  a second backend. Real GUI verification requires a disposable, authorized
+  target.
+
+## Validation
+
+- Build the package with `scripts/build-package.sh OUTPUT_DIRECTORY`, then
+  inspect it with the host's package validation and installation tests. Keep
+  test evidence outside the repository.
+
+## 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.