docs: generate AGENTS.md from agent instruction units

.agent/agents.json

@@ -0,0 +1,7 @@
+{
+  "instructions": {
+    "agents": ["claude-code", "codex"],
+    "sections": ["guide"]
+  },
+  "sources": {}
+}

.agent/agents.resolved

@@ -0,0 +1,24 @@
+{
+  "instructions": {
+    "chatgpt": {},
+    "sections": [
+      {
+        "hash": "sha256:e9e56cb5f7771d0c97062dd3bffdf2ac93596d911771a49536d38200f5b6ee57",
+        "name": "guide",
+        "path": ".agent/instructions/guide.md",
+        "source": "."
+      }
+    ],
+    "targets": {
+      "AGENTS.md": {
+        "agents": ["claude-code", "codex"],
+        "blockHash": "sha256:876da536153d59a8ec8f23019a87b6e0324e44fb79e4c9f892852ba9f9539657",
+        "created": false,
+        "headingOffset": 0
+      }
+    }
+  },
+  "skills": {},
+  "sources": {},
+  "version": 1
+}

.agent/instructions/guide.md

@@ -0,0 +1,42 @@
+---
+description: Route changes to computer-mcp organization data, conventions, design assets and shared instruction units.
+---
+# Organization Agent Guide
+
+Read `README.md` first for repository purpose and entry points.
+
+## Task Route
+
+- For the public organization entry point, edit `profile/catalog.json` and
+  regenerate `profile/README.md`; `README.md` gives the commands.
+- For conventions shared by every repository, read `MAINTENANCE.md`.
+- Before changing shared version, plugin compatibility or dependency rules,
+  read `VERSIONING.md`.
+- For repository settings, GitHub Apps and Actions credentials, change
+  `MAINTENANCE.md` with the setting; the organization check in
+  [computer-mcp/github-workflows](https://github.com/computer-mcp/github-workflows)
+  compares it with live settings.
+- For visual identity, read `DESIGN.md`. Icon sources and their provenance live
+  in `.github/design/icons/`, fonts in `.github/design/fonts/`, and `README.md`
+  gives the generator and toolchain commands.
+- For a reusable workflow or a check more than one repository needs, work in
+  `computer-mcp/github-workflows`; this repository keeps only thin callers.
+- For positioning, the tagline and other text rendered into images, read the
+  main repository's
+  [ProductIdentity](https://github.com/computer-mcp/computer-mcp/blob/master/Documentation/Architecture/ProductIdentity.md).
+- `.agent/instructions/shared/` holds the instruction units member plugins
+  install; state only rules that hold for every member plugin, and regenerate
+  the plugins after changing them.
+
+## Repository Guardrails
+
+- Text rendered into images must match ProductIdentity. Preserve repository
+  visibility and integration ownership.
+- Change `DESIGN.md` or `profile/catalog.json`, regenerate, and commit inputs
+  and outputs together. Never edit generated files by hand.
+- Before committing, lint DESIGN and check the profile with the
+  `github-readme-design` toolchain.
+- Deliver icons and social previews to other repositories through a pull
+  request in each repository, and record each consumed copy in the icon's
+  `provenance.json`.
+- Profile content must be understandable from committed artifacts alone.

.agent/instructions/shared/plugin-rules.md

@@ -0,0 +1,23 @@
+---
+description: Keep a Computer MCP plugin free of vendor software and host authority, and validate its package before handoff.
+---
+## 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.

.github/workflows/ci.yml

@@ -39,7 +39,7 @@ jobs:
   organization:
     permissions:
       contents: read
-    uses: computer-mcp/github-workflows/.github/workflows/organization.yml@d65bc20504f39c3a30232d67043abeca43d2c7b1
+    uses: computer-mcp/github-workflows/.github/workflows/organization.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       # The catalog under review must match the live inventory and About sentences.
       declaration-revision: ${{ github.event.pull_request.head.sha || github.sha }}

.github/workflows/source-policy.yml

@@ -11,7 +11,7 @@ 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:
       # A pull request is checked against the accepted rules, not the rules it proposes.
       declaration-revision: ${{ github.event.pull_request.base.sha || github.sha }}

.gitignore

@@ -1,3 +1,6 @@
-.agent/
 __pycache__/
 .DS_Store
+/.agent/*
+!/.agent/instructions/
+!/.agent/agents.json
+!/.agent/agents.resolved

AGENTS.md

@@ -1,70 +1,8 @@
+<!-- Generated by agents from instruction files. Edit those files and run `agents update`. -->
+
 # Organization 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
 
@@ -77,81 +15,17 @@ Use this check:
   `MAINTENANCE.md` with the setting; the organization check in
   [computer-mcp/github-workflows](https://github.com/computer-mcp/github-workflows)
   compares it with live settings.
-- For visual identity, read `DESIGN.md`. Icon sources and their provenance
-  live in `.github/design/icons/`, fonts in `.github/design/fonts/`, and
-  `README.md` gives the generator and toolchain commands.
+- For visual identity, read `DESIGN.md`. Icon sources and their provenance live
+  in `.github/design/icons/`, fonts in `.github/design/fonts/`, and `README.md`
+  gives the generator and toolchain commands.
 - For a reusable workflow or a check more than one repository needs, work in
   `computer-mcp/github-workflows`; this repository keeps only thin callers.
 - For positioning, the tagline and other text rendered into images, read the
   main repository's
   [ProductIdentity](https://github.com/computer-mcp/computer-mcp/blob/master/Documentation/Architecture/ProductIdentity.md).
-- For the default community files, use the root governance files,
-  `.github/ISSUE_TEMPLATE/` and the pull request template.
-- 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.md` indexes scope, icon generation, profile and social-preview
-  rendering, and delivery.
-- `MAINTENANCE.md` is current truth for cross-repository operating conventions.
-  `VERSIONING.md` owns shared version and dependency rules; each repository
-  owns its version sources, release procedure and written exceptions.
-- `DESIGN.md` is current truth for visual identity and `profile/catalog.json`
-  for the profile's repositories, groups and sentences. `profile/README.md`
-  and the social previews are rendered from them; consumed icon copies are
-  recorded in each icon's `provenance.json`.
-- The main repository's ProductIdentity is current truth for product meaning.
-- Root governance files and `.github/*` are GitHub-facing governance and the
-  organization's default community files.
-
-## 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, the profile, `MAINTENANCE.md`, `DESIGN.md` and the community
-files. Change history belongs in commits and pull requests.
-
-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.
+- `.agent/instructions/shared/` holds the instruction units member plugins
+  install; state only rules that hold for every member plugin, and regenerate
+  the plugins after changing them.
 
 ## Repository Guardrails
 
@@ -164,5 +38,4 @@ source of truth instead of a literal value.
 - Deliver icons and social previews to other repositories through a pull
   request in each repository, and record each consumed copy in the icon's
   `provenance.json`.
-- Keep `.agent/` local and untracked. Profile content must be understandable
-  from committed artifacts alone.
+- Profile content must be understandable from committed artifacts alone.

MAINTENANCE.md

@@ -127,8 +127,10 @@ an Actions credential, and update this section in the same change.
 - GitHub presentation assets live in `.github/assets/`: `logo/` with
   `logo-light.png` and `logo-dark.png`, `social-preview/social-preview.png`,
   and `terminal/` or `screenshots/` where the product has them.
-- `AGENTS.md` carries the shared first-principles and canonical-artifact
-  sections, then routes agents through the repository's own documents.
+- `AGENTS.md` is generated by `agents` from the repository's instruction
+  units in `.agent/instructions/`; member plugins also install this
+  repository's `shared/` units. Commit the units, `.agent/agents.json`,
+  `.agent/agents.resolved` and the generated files together; the rest of
   `.agent/` stays local and untracked.
 
 ## Community files