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:e3960ba79cc4c2a9b0bbbcb3f6a6584e5bd6b672c560ad12a4ff3eaedbd4c638",
+        "name": "guide",
+        "path": ".agent/instructions/guide.md",
+        "source": "."
+      }
+    ],
+    "targets": {
+      "AGENTS.md": {
+        "agents": ["claude-code", "codex"],
+        "blockHash": "sha256:3031290818c2d1c0ad17efb4d27255a97796e1942fa77195ac78f798a95c5dd3",
+        "created": false,
+        "headingOffset": 0
+      }
+    }
+  },
+  "skills": {},
+  "sources": {},
+  "version": 1
+}

.agent/instructions/guide.md

@@ -0,0 +1,33 @@
+---
+description: Route apple-cli changes through its architecture documents and keep each command target independent.
+---
+# apple-cli Agent Guide
+
+## Task Route
+
+- Before changing versions, dependencies, packaging or release workflows, read
+  `VERSIONING.md` and `Documentation/Reference/Release.md`, and use the release
+  reference's check entry points.
+- Before changing a command target or the CLI contract, read the relevant
+  document in `Documentation/Architecture/`; the target catalog is in
+  `RepositoryIdentity.md` and `TargetFirstCli.md`, the accepted capabilities in
+  `CapabilityList.md`. Target-specific architecture lives in
+  `Documentation/Architecture/<Target>/` and target usage in
+  `Documentation/Reference/<Target>/`.
+- For agent integration and usage guidance, update
+  `Documentation/Architecture/CliContract.md` and
+  `Documentation/Reference/AppleCLIUserGuide.md`.
+
+## Implementation Boundary
+
+- Each `<Target>CLI` module owns its typed `swift-argument-parser` command
+  tree, target-local validation, behavior, diagnostics, and mutation or
+  external-action safety policy. `AppleCLI` only composes the root `apple`
+  command, and `apple-cli-mcp` is an adapter over the CLI contract.
+- `AppleMCPServer` and `AppleMCPAdapter` use the official MCP Swift SDK
+  directly; business modules do not import MCP.
+- SwiftPM target and module names use Swift identifier style, such as
+  `NotesCLI`. The products stay `apple` and `apple-cli-mcp`, and command
+  targets stay lowercase under `apple`, such as `apple notes`.
+- External projects are inputs for target-local reuse decisions, never this
+  repository's architecture truth.

.github/workflows/ci.yml

@@ -50,7 +50,7 @@ jobs:
           if-no-files-found: ignore
   demo:
     needs: package
-    uses: computer-mcp/github-workflows/.github/workflows/terminal-demo.yml@53ecce59bf7ed184528b2f7894c864f338932d37
+    uses: computer-mcp/github-workflows/.github/workflows/terminal-demo.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       artifact: apple-cli-macos-arm64-candidate-${{ github.run_id }}-${{ github.run_attempt }}
       archive: apple-cli-*-macos-arm64.tar.gz
@@ -59,6 +59,6 @@ jobs:
   validate:
     if: always()
     needs: [package, demo]
-    uses: computer-mcp/github-workflows/.github/workflows/result.yml@53ecce59bf7ed184528b2f7894c864f338932d37
+    uses: computer-mcp/github-workflows/.github/workflows/result.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       needs-json: ${{ toJSON(needs) }}

.github/workflows/source-policy.yml

@@ -12,7 +12,7 @@ concurrency:
   cancel-in-progress: true
 jobs:
   policy:
-    uses: computer-mcp/github-workflows/.github/workflows/policy.yml@53ecce59bf7ed184528b2f7894c864f338932d37
+    uses: computer-mcp/github-workflows/.github/workflows/policy.yml@fd25fcface41732fda099017c6945912366fc7c1
     with:
       declaration-revision: 5c54a40cb7953db7472ebbefd3db608036b7b3ab
       path-exceptions: |

.gitignore

@@ -1,5 +1,4 @@
 .DS_Store
-/.agent/
 /.build
 __pycache__/
 *.pyc
@@ -17,3 +16,7 @@ DerivedData/
 !.env.template
 *.p12
 *.pfx
+/.agent/*
+!/.agent/instructions/
+!/.agent/agents.json
+!/.agent/agents.resolved

AGENTS.md

@@ -1,228 +1,32 @@
-# apple-cli 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.
+<!-- Generated by agents from instruction files. Edit those files and run `agents update`. -->
 
-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.
+# apple-cli Agent Guide
 
 ## Task Route
 
 - Before changing versions, dependencies, packaging or release workflows, read
   `VERSIONING.md` and `Documentation/Reference/Release.md`, and use the release
-  reference's existing 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
-
-This repository is a CLI-first SwiftPM package. Validate Swift package changes
-with package-local build or test checks.
-
-Current architecture truth lives in `Documentation/Architecture/`:
-
-- `RepositoryIdentity.md`
-- `TargetFirstCli.md`
-- `CapabilityList.md`
-- `CliContract.md`
-- `McpAdapterBoundary.md`
-- `TargetImplementationMechanisms.md`
-- `Intelligence/Architecture.md`
-
-- `Documentation/Architecture/<Target>/*` owns target-specific architecture
-  truth and capability lists, for example
-  `Documentation/Architecture/Reminders/CapabilityList.md`.
-- `Documentation/Reference/<Target>/*` owns target-specific user guides,
-  developer guides, and validation references.
-- `Package.swift` owns SwiftPM package structure.
-- For agent integration and usage guidance, route to
+  reference's check entry points.
+- Before changing a command target or the CLI contract, read the relevant
+  document in `Documentation/Architecture/`; the target catalog is in
+  `RepositoryIdentity.md` and `TargetFirstCli.md`, the accepted capabilities in
+  `CapabilityList.md`. Target-specific architecture lives in
+  `Documentation/Architecture/<Target>/` and target usage in
+  `Documentation/Reference/<Target>/`.
+- For agent integration and usage guidance, update
   `Documentation/Architecture/CliContract.md` and
-  `Documentation/Reference/AppleCLIUserGuide.md`. Target-specific usage
-  guidance belongs in `Documentation/Reference/<Target>/UserGuide.md` when that
-  target has a dedicated reference directory.
-- Do not inherit external product architecture or promote raw external project
-  facts into architecture truth. External sources are inputs for target-local
-  reuse decisions, not the source of this repository's architecture.
+  `Documentation/Reference/AppleCLIUserGuide.md`.
 
 ## Implementation Boundary
 
-Keep target ownership independent. The package declares exactly two executable
-products:
-
-- `apple`
-- `apple-cli-mcp`
-
-`apple` is the canonical target-first CLI. `apple-cli-mcp` is an adapter over
-that CLI contract.
-
-The accepted command targets under `apple` are:
-
-- `notes`
-- `calendar`
-- `reminders`
-- `contacts`
-- `mail`
-- `messages`
-- `maps`
-- `finder`
-- `numbers`
-- `pages`
-- `keynote`
-- `facetime`
-- `safari`
-- `photos`
-- `print`
-- `clipboard`
-- `notifications`
-- `intelligence`
-- `tcc`
-
-Each `<Target>CLI` module owns its typed `swift-argument-parser` command tree,
-target-local validation, implementation behavior, diagnostics, and mutation or
-external-action safety policy. `AppleCLI` only composes the root `apple`
-command. `AppleMCPServer` and `AppleMCPAdapter` use the official MCP Swift SDK
-directly; business modules do not import MCP.
-
-The complete target catalog lives in
-`Documentation/Architecture/RepositoryIdentity.md` and
-`Documentation/Architecture/TargetFirstCli.md`. The current accepted target
-capability surface lives in
-`Documentation/Architecture/CapabilityList.md`.
-
-SwiftPM target/module names should use Swift identifier style, for example
-`NotesCLI`. CLI products remain `apple` and `apple-cli-mcp`; command targets
-stay lowercase under `apple`, for example `apple notes`.
+- Each `<Target>CLI` module owns its typed `swift-argument-parser` command
+  tree, target-local validation, behavior, diagnostics, and mutation or
+  external-action safety policy. `AppleCLI` only composes the root `apple`
+  command, and `apple-cli-mcp` is an adapter over the CLI contract.
+- `AppleMCPServer` and `AppleMCPAdapter` use the official MCP Swift SDK
+  directly; business modules do not import MCP.
+- SwiftPM target and module names use Swift identifier style, such as
+  `NotesCLI`. The products stay `apple` and `apple-cli-mcp`, and command
+  targets stay lowercase under `apple`, such as `apple notes`.
+- External projects are inputs for target-local reuse decisions, never this
+  repository's architecture truth.