Docs: add guided aps workflows

.gitignore

@@ -10,5 +10,12 @@ DerivedData/
 *.swp
 *~
 
+# Repository-local state roots created by guided examples
+/.agents/
+/.release-state/
+/.aps-agent-example/
+/.aps-release-example/
+/.aps-swift-harness-example/
+
 # CorvidLabs trust toolchain
 augur.json

.specsync/change-sequence.json

@@ -1,6 +1,6 @@
 {
   "schema_version": 1,
-  "sequence": 64,
-  "id": "CHG-0064-fix-release-workflow-fetch-authentication-so-signed-tags-and-attest-notes-can-be",
+  "sequence": 66,
+  "id": "CHG-0066-document-and-ignore-repository-local-state-roots-generated-by-guided-examples",
   "acknowledged_collisions": []
 }

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/change.md

@@ -0,0 +1,24 @@
+---
+id: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+state: accepted
+type: documentation
+base_commit: 5a14806518b38ffdb5143c3115f1761689f8c749
+---
+
+# Add runnable agent, CI, Swift integration, and release pipeline examples with README and documentation navigation
+
+## Intent
+
+Add runnable agent, CI, Swift integration, and release pipeline examples with README and documentation navigation
+
+## Affected Canonical Specs
+
+- `aps-cli`
+
+## Acceptance Criteria
+
+- Four documented examples cover agent memory, GitHub Actions, Swift/AppState integration, and release pipelines; shell examples pass an automated contract test; README and docs link to every example; guidance clearly states persistence, multi-writer, cross-job, and secret-handling boundaries.
+
+## No-spec Rationale
+
+This adds examples and explanatory documentation for existing v1.1.0 commands without changing the CLI contract.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/context.md

@@ -0,0 +1,15 @@
+---
+change: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+artifact: context
+---
+
+# Context
+
+aps already exposes the primitives needed by agents and automation, but the
+README demonstrates commands in isolation. Users need complete examples that
+show state-root isolation, persistent dynamic keys, cross-process reads,
+cross-job transfer, Swift-driven integration, and release checkpoints.
+
+The examples must remain honest about the product boundary: aps is local typed
+state, not a distributed lock, secret manager, message queue, or replacement
+for GitHub outputs.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/design.md

@@ -0,0 +1,18 @@
+---
+change: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+artifact: design
+---
+
+# Design
+
+Add an `examples/` index with four focused examples:
+
+1. Agent memory uses a dedicated `APS_HOME` and persistent FileState keys.
+2. GitHub Actions transfers a state root between jobs as an artifact.
+3. A Swift harness drives the AppState-backed CLI as an integration boundary.
+4. A release pipeline records version, commit, phase, tests, and risk.
+
+Shell examples accept `APS_BIN` and `APS_HOME` so automated tests can run them
+against an isolated build. The Swift example compiles into a temporary
+directory. Documentation links to the examples from both navigation entry
+points and explains when simpler native primitives remain preferable.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/docs.md

@@ -0,0 +1,14 @@
+---
+change: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+artifact: docs
+---
+
+# Docs
+
+- Update the root README to reflect the published v1.1.0 release and introduce
+  the guided examples.
+- Add `docs/use-cases.md` for project selection, agents, CI, Swift harnesses,
+  release pipelines, state-root layouts, and safety boundaries.
+- Update `docs/README.md` with the new use-case and example entry points.
+- Give every example its own README with setup, expected behavior, and
+  production caveats.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/state.json

@@ -0,0 +1,41 @@
+{
+  "schema_version": 1,
+  "id": "CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re",
+  "slug": "add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re",
+  "title": "Add runnable agent, CI, Swift integration, and release pipeline examples with README and documentation navigation",
+  "description": "Add runnable agent, CI, Swift integration, and release pipeline examples with README and documentation navigation",
+  "kind": "documentation",
+  "state": "accepted",
+  "canonical_applied": true,
+  "base_commit": "5a14806518b38ffdb5143c3115f1761689f8c749",
+  "created_at": 1785333608,
+  "updated_at": 1785344239,
+  "affected_specs": [
+    "aps-cli"
+  ],
+  "affected_paths": [
+    "README.md",
+    "docs",
+    "examples",
+    "Scripts/test-examples.sh",
+    "fledge.toml",
+    ".specsync/change-sequence.json"
+  ],
+  "no_spec_change": true,
+  "no_spec_change_rationale": "This adds examples and explanatory documentation for existing v1.1.0 commands without changing the CLI contract.",
+  "acceptance_criteria": [
+    "Four documented examples cover agent memory, GitHub Actions, Swift/AppState integration, and release pipelines; shell examples pass an automated contract test; README and docs link to every example; guidance clearly states persistence, multi-writer, cross-job, and secret-handling boundaries."
+  ],
+  "selected_artifacts": [
+    "context",
+    "docs",
+    "design",
+    "tasks",
+    "testing"
+  ],
+  "dependencies": [],
+  "answers": {
+    "architecture_risk": "no",
+    "public_contract": "no"
+  }
+}

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/tasks.md

@@ -0,0 +1,11 @@
+---
+change: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+artifact: tasks
+---
+
+# Tasks
+
+- [x] Add the four guided examples and their local documentation.
+- [x] Add the use-case guide and update README navigation and release copy.
+- [x] Add executable example contract coverage to the Fledge verification lane.
+- [x] Run local verification and prepare the documentation PR.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/testing.md

@@ -0,0 +1,12 @@
+---
+change: CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re
+artifact: testing
+---
+
+# Testing
+
+- `Scripts/test-examples.sh` runs both shell examples against isolated roots,
+  compiles and runs the Swift harness, and checks the GitHub Actions contract.
+- The example contract is part of `fledge lanes run verify`.
+- `specsync change verify ... --strict` runs the complete project gate before
+  acceptance.

.specsync/changes/CHG-0065-add-runnable-agent-ci-swift-integration-and-release-pipeline-examples-with-re/verification-attempts.json

@@ -0,0 +1,155 @@
+{
+  "schema_version": 1,
+  "attempts": [
+    {
+      "timestamp": 1785334380,
+      "commit": "5a14806518b38ffdb5143c3115f1761689f8c749",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "d63ebd72a27f20abfe97f164f13694afd85de075f3cc6ee7b84bf932183f3b62",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785336293,
+      "commit": "3a0121b3de4caada98f79b871c77a1cbb83c26fd",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "d63ebd72a27f20abfe97f164f13694afd85de075f3cc6ee7b84bf932183f3b62",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785338977,
+      "commit": "eb55402e4b5d52ee0231ea306a3edcccd6ae038c",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "d63ebd72a27f20abfe97f164f13694afd85de075f3cc6ee7b84bf932183f3b62",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785339903,
+      "commit": "7a151837dded09817eff7fc71431404ac8bdcfc5",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "54a1b9dc8f2bf6184fb2cfa677ca4b9acc3a5387d9833ebbedde53c19249e212",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785340853,
+      "commit": "2f13cde531c3953d1f821b15a699449d0a1e6f03",
+      "contract_digest": "afa9871e790e9cfa628d4fbff52f86d5c47ee4fb1722fa5f1cf59571ad303453",
+      "workspace_digest": "da4c8bb24a069922d6e6f698130660938df9fbc76db2e9ff4d2251b568164b5c",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785340957,
+      "commit": "2f13cde531c3953d1f821b15a699449d0a1e6f03",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "da4c8bb24a069922d6e6f698130660938df9fbc76db2e9ff4d2251b568164b5c",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785342053,
+      "commit": "5574c48824513a06961699b3da0d6728b7b372d3",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "e8184fcdb2e7740e5655c36f62b737aec4a60f11498d32a613d04b47a6230972",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785342971,
+      "commit": "27eec40659a5756d53758309214059164f0b4286",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "7a25a434cb66ec5e457160fc5b866feb36e0a9368b491c46a0276063ad096dc9",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785343551,
+      "commit": "699bdd6b6b3584e67b8525aa447ddfe4dc5dda0f",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "2d134d41619b9a533b9a6cf98ed352a25e4b069b6a7ec7b7a1ecf99597e1a808",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    },
+    {
+      "timestamp": 1785344234,
+      "commit": "c4e7d71ad334ebefb35cbbb669f54abfee0d8935",
+      "contract_digest": "85242c6d7e18a7e56480153d437ddefe8086c2a25c72df7afe6073f4e8f9ac00",
+      "workspace_digest": "5a4c3896bd0c89603c4686ab7888831af46a383104cb00b983448b7e36f07ce2",
+      "passed": true,
+      "commands": [
+        {
+          "command": "fledge lanes run verify",
+          "success": true,
+          "exit_code": 0
+        }
+      ],
+      "requirement_ids": []
+    }
+  ]
+}