recall-os 0.2.1 → 0.3.1

package/examples/generated-flutter/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-flutter/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-flutter/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-generic/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-generic/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-generic/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-ios-swift/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-ios-swift/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-ios-swift/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-kotlin-android/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-kotlin-android/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-kotlin-android/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-laravel-api/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-laravel-api/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-laravel-api/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-laravel-react/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-laravel-react/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-laravel-react/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-laravel-vue/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-laravel-vue/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-laravel-vue/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-nextjs/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-nextjs/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.

package/examples/generated-nextjs/docs/ai/RECALL_COMMANDS.md

@@ -108,6 +108,17 @@ Options:
 - `--dry-run`: show planned writes without writing files.
 - `--force`: overwrite existing files explicitly.
 
+### `recall adr supersede <old> <new-title>`
+
+Record a changed decision. Marks an accepted ADR as `Accepted — superseded by ADR-####` and creates
+a new accepted ADR that declares what it supersedes, so the reasoning trail stays auditable instead
+of being overwritten. Doctor then warns about any memory still referencing the superseded decision.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
 ### `recall module create <name>`
 
 Create module memory docs under the configured modules directory.
@@ -124,7 +135,8 @@ engineering evidence is present, and whether memory references decisions that ex
 accepted.
 
 Doctor also runs deterministic drift checks: feature or module memory that references a missing ADR
-is an error, and memory that references a not-yet-accepted ADR is a warning.
+is an error, memory that references a not-yet-accepted ADR is a warning, and memory that still
+references a superseded decision is a warning.
 
 Exit codes:
 

package/examples/generated-python-fastapi/AGENTS.md

@@ -13,3 +13,31 @@ Required reading:
 - `docs/60-engineering/ENGINEERING_STANDARDS.md`
 
 Repository rules override model preferences. If instructions conflict, stop and report the conflict.
+
+## Recall OS commands
+
+This repository is maintained with the Recall OS CLI. Use these commands yourself as you work — do
+not ask the human to run them, and do not search the web for them (this is a project-local tool):
+
+- `recall doctor` — validate repository memory; run it before claiming any work is complete.
+- `recall feature create <name>` — scaffold feature memory before non-trivial feature work.
+- `recall adr create <title>` — propose a decision; `recall adr accept <name>` accepts it.
+- `recall adr supersede <old> <new-title>` — record a changed decision (never overwrite an accepted
+  ADR).
+- `recall module create <name>` — scaffold module memory for a new responsibility boundary.
+- `recall mcp add <server>` — capture an MCP tool's context into memory, offline.
+
+Full command reference: `docs/ai/RECALL_COMMANDS.md`.
+
+## Changing an accepted decision
+
+Before changing anything an accepted ADR governs (framework, database, auth, API shape, and
+similar):
+
+1. Check `docs/adrs/` for an accepted ADR that covers it.
+2. If your change contradicts one, stop and confirm with a human first — do not silently change the
+   code and leave the ADR saying the opposite.
+3. Record the change as a new decision with `recall adr supersede <old> <new-title>`. That
+   supersedes the old ADR instead of overwriting history, so the reasoning stays auditable.
+
+Repository memory is only trustworthy if decisions change through this trail, not silently.

package/examples/generated-python-fastapi/docs/60-engineering/AI_AGENT_RULES.md

@@ -4,3 +4,12 @@ AI agents must follow repository memory over model preference.
 
 If a request conflicts with accepted repository memory or engineering standards, stop and report the
 conflict.
+
+## Changing an accepted decision
+
+When work would change something an accepted ADR governs:
+
+1. Find the accepted ADR in `docs/adrs/` that covers it.
+2. If the change contradicts it, stop and confirm with a human before changing the code.
+3. Record the new decision with `recall adr supersede <old> <new-title>` so the old ADR is marked
+   superseded and the reasoning is preserved, instead of silently editing or contradicting it.