recall-os 0.1.0

package/examples/generated-ios-swift/docs/ai/presets/ios-swift-guidance.md

@@ -0,0 +1,30 @@
+# iOS Swift Preset Guidance
+
+This is proposed guidance, not accepted. Convert any choice you adopt into an accepted ADR in
+repository memory. Until then, treat everything here as a recommendation awaiting human review.
+
+## Decision forks this stack forces
+
+- UI framework: SwiftUI vs UIKit.
+- Concurrency: Swift async/await with the Observation framework vs Combine.
+- Persistence: SwiftData vs Core Data.
+- Presentation pattern: MVVM vs The Composable Architecture (TCA).
+- Testing: XCTest vs the Swift Testing framework.
+
+## Recommended structure (proposed)
+
+- Feature folders with view, model, and view-model separation.
+- A dependency layer abstracted behind protocols for testability.
+- Swift Package Manager for modular code.
+
+## Testing (proposed)
+
+- Unit tests with XCTest or Swift Testing.
+- View-model tests independent of the UI.
+- Snapshot or UI tests for critical flows.
+
+## Security considerations (proposed)
+
+- Store credentials and tokens in the Keychain, never in source or UserDefaults.
+- Enable App Transport Security and consider certificate pinning.
+- Avoid logging sensitive data.

package/examples/generated-kotlin-android/.recall/config.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.1.0",
+  "templateVersion": "0.1.0",
+  "preset": "kotlin-android",
+  "memoryProfile": "standard",
+  "mode": "standard",
+  "aiTools": [
+    "claude",
+    "codex"
+  ],
+  "docsDir": "docs",
+  "featuresDir": "docs/40-features",
+  "modulesDir": "docs/30-modules",
+  "adrDir": "docs/adrs",
+  "writePolicy": "skip-existing",
+  "preCommitGates": []
+}

package/examples/generated-kotlin-android/.recall/hooks/pre-commit

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Recall OS pre-commit hook.
+# Generated by `recall init`. Edit gates in .recall/config.json (preCommitGates),
+# then re-run `recall init --force` to regenerate this hook.
+# Enable once per clone with:
+#   git config core.hooksPath .recall/hooks
+set -e
+
+recall doctor

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

@@ -0,0 +1,15 @@
+# generated-kotlin-android Agent Instructions
+
+This repository uses Recall OS repository memory.
+
+Start with durable source-of-truth docs under `docs/`.
+
+Required reading:
+
+- `docs/00-product/PRD.md`
+- `docs/10-architecture/ARCHITECTURE.md`
+- `docs/20-security/SECURITY_MODEL.md`
+- `docs/50-quality/QUALITY_GATES.md`
+- `docs/60-engineering/ENGINEERING_STANDARDS.md`
+
+Repository rules override model preferences. If instructions conflict, stop and report the conflict.

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

@@ -0,0 +1,7 @@
+# generated-kotlin-android Claude Instructions
+
+Use this file as a short routing guide.
+
+The durable project memory lives in `docs/`. Do not rely on chat history as source of truth.
+
+Read `AGENTS.md` and the relevant docs before changing code or repository memory.

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

@@ -0,0 +1,11 @@
+# Kotlin Android Example
+
+This folder shows the repository memory generated by:
+
+```bash
+recall init --preset kotlin-android
+```
+
+The Kotlin Android preset adds opinionated, proposed guidance and proposed ADRs for the stack's real
+decision forks (Compose, coroutines and Flow, dependency injection, persistence, and presentation
+pattern). It does not create application code or silently accept architecture choices.

package/examples/generated-kotlin-android/docs/00-product/BRD.md

@@ -0,0 +1,9 @@
+# BRD: generated-kotlin-android
+
+## Purpose
+
+Describe the business goal, target users, and success criteria for this repository.
+
+## Current Status
+
+Draft.

package/examples/generated-kotlin-android/docs/00-product/PRD.md

@@ -0,0 +1,13 @@
+# PRD: generated-kotlin-android
+
+## Purpose
+
+Describe what this repository is building and why.
+
+## Current Status
+
+Draft.
+
+## Notes
+
+Keep product intent durable here. Do not rely on chat history as source of truth.

package/examples/generated-kotlin-android/docs/10-architecture/ARCHITECTURE.md

@@ -0,0 +1,11 @@
+# Architecture
+
+## Purpose
+
+Describe the accepted architecture for this repository.
+
+## Current Status
+
+No architecture decisions are accepted yet.
+
+Use ADRs to accept architecture choices.

package/examples/generated-kotlin-android/docs/10-architecture/FILE_WRITE_POLICY.md

@@ -0,0 +1,8 @@
+# File Write Policy
+
+Default behavior:
+
+- Skip existing files.
+- Use dry run before risky writes.
+- Require explicit force to overwrite.
+- Never write outside the repository root.

package/examples/generated-kotlin-android/docs/10-architecture/MEMORY_ENGINE.md

@@ -0,0 +1,16 @@
+# Repository Memory
+
+Repository memory is the durable source of truth for humans and AI agents.
+
+Source-of-truth order:
+
+1. Accepted ADRs and repository decisions
+2. Architecture docs
+3. Engineering standards
+4. Current PRD and accepted change requests
+5. Security and testing docs
+6. Module docs
+7. Feature plans
+8. Task files
+9. External context
+10. Chat history

package/examples/generated-kotlin-android/docs/20-security/SECURITY_MODEL.md

@@ -0,0 +1,11 @@
+# Security Model
+
+## Current Status
+
+Draft.
+
+## Baseline Rules
+
+- Do not commit secrets.
+- Do not read or copy `.env` files into docs.
+- Do not add network, telemetry, cloud, MCP runtime, or AI API behavior without explicit review.

package/examples/generated-kotlin-android/docs/20-security/THREAT_MODEL.md

@@ -0,0 +1,7 @@
+# Threat Model
+
+## Current Status
+
+Draft.
+
+Track repository-specific risks here as the project evolves.

package/examples/generated-kotlin-android/docs/30-modules/README.md

@@ -0,0 +1,17 @@
+# Module Memory
+
+Module memory records what each important module owns, how it should be tested, and which decisions
+affect it.
+
+Future module folders should use:
+
+```txt
+docs/30-modules/<module>/
+  MODULE.md
+  TASKS.md
+  TEST_PLAN.md
+  DECISIONS.md
+```
+
+Agents should update module memory when implementation changes responsibilities, boundaries, tests,
+risks, or decisions.

package/examples/generated-kotlin-android/docs/40-features/README.md

@@ -0,0 +1,22 @@
+# Feature Memory
+
+Feature memory records requirements, acceptance criteria, plans, tests, reviews, and completion
+evidence.
+
+Future feature folders should use:
+
+```txt
+docs/40-features/F-###-<feature>/
+  PRD.md
+  ACCEPTANCE.md
+  ARCHITECTURE_IMPACT.md
+  CHANGE_REQUESTS.md
+  PLAN.md
+  TASKS.md
+  TEST_PLAN.md
+  REVIEW.md
+  COMPLETION_REPORT.md
+```
+
+Agents should not implement meaningful feature work without a feature plan or clear source-of-truth
+reference.

package/examples/generated-kotlin-android/docs/50-quality/QUALITY_GATES.md

@@ -0,0 +1,11 @@
+# Quality Gates
+
+Do not claim completion without evidence.
+
+Completion evidence should include:
+
+- Files changed.
+- Tests run.
+- Results.
+- Skipped checks.
+- Remaining risks.

package/examples/generated-kotlin-android/docs/50-quality/TESTING_STRATEGY.md

@@ -0,0 +1,5 @@
+# Testing Strategy
+
+Tests should derive from acceptance criteria, risk, security invariants, and module boundaries.
+
+Document required unit, integration, security, and golden tests as the repository grows.

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

@@ -0,0 +1,6 @@
+# AI Agent Rules
+
+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.

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

@@ -0,0 +1,11 @@
+# Engineering Standards
+
+Repository rules override model preferences.
+
+Baseline rules:
+
+- Never commit secrets.
+- Keep changes scoped.
+- Update docs when behavior or architecture changes.
+- Add tests or document why tests were skipped.
+- Do not claim completion without evidence.

package/examples/generated-kotlin-android/docs/adrs/README.md

@@ -0,0 +1,5 @@
+# Architecture Decision Records
+
+Accepted architecture choices belong here.
+
+Presets and AI agents may propose decisions, but humans accept them.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-architecture-mvvm.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use MVVM
+
+## Status
+
+Proposed
+
+## Context
+
+The app needs a presentation architecture for separating UI from logic.
+
+## Decision
+
+Consider MVVM with unidirectional state from ViewModels, awaiting human acceptance.
+
+## Alternatives Considered
+
+- MVI with explicit intents and reducers.
+- Plain ViewModels without a strict pattern.
+
+## Consequences
+
+- Clear separation of UI and state.
+- Teams must agree on state and event conventions.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-async-coroutines.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Coroutines and Flow
+
+## Status
+
+Proposed
+
+## Context
+
+The app needs a concurrency and reactive streams approach.
+
+## Decision
+
+Consider Kotlin Coroutines with Flow for asynchronous work and streams, awaiting human acceptance.
+
+## Alternatives Considered
+
+- RxJava/RxKotlin.
+- Callbacks and `LiveData` only.
+
+## Consequences
+
+- Structured concurrency and cancellation.
+- Requires discipline around dispatchers and scope.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-di-hilt.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Hilt
+
+## Status
+
+Proposed
+
+## Context
+
+The app needs a dependency injection approach for testability and lifecycle scoping.
+
+## Decision
+
+Consider Hilt for dependency injection, awaiting human acceptance.
+
+## Alternatives Considered
+
+- Koin.
+- Manual constructor injection.
+
+## Consequences
+
+- Compile-time validation and Android lifecycle scopes.
+- Adds annotation processing to the build.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-persistence-room.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Room
+
+## Status
+
+Proposed
+
+## Context
+
+The app needs structured local persistence.
+
+## Decision
+
+Consider Room for local relational persistence, awaiting human acceptance.
+
+## Alternatives Considered
+
+- SQLDelight.
+- DataStore for simple key-value needs.
+
+## Consequences
+
+- Compile-time verified SQL and Flow integration.
+- Schema migrations must be maintained.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-platform.md

@@ -0,0 +1,24 @@
+# Proposed ADR: Use Kotlin for Android
+
+## Status
+
+Proposed
+
+## Context
+
+The team needs a primary language and platform for the Android application.
+
+## Decision
+
+Consider Kotlin as the Android application language. This is not accepted until a human reviews and
+accepts it.
+
+## Alternatives Considered
+
+- Java for Android.
+- A cross-platform stack such as Flutter or React Native.
+
+## Consequences
+
+- Idiomatic Android APIs and coroutines support.
+- Requires Kotlin proficiency across the team.

package/examples/generated-kotlin-android/docs/adrs/proposed/ADR-PROPOSED-kotlin-android-ui-compose.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Jetpack Compose
+
+## Status
+
+Proposed
+
+## Context
+
+The app needs a UI toolkit. Compose and the legacy View/XML system are the main options.
+
+## Decision
+
+Consider Jetpack Compose as the UI toolkit, awaiting human acceptance.
+
+## Alternatives Considered
+
+- Android Views with XML layouts.
+- A hybrid of Compose and Views during migration.
+
+## Consequences
+
+- Declarative UI and less boilerplate.
+- Requires Compose tooling and team ramp-up.

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

@@ -0,0 +1,7 @@
+# AI Agents, Skills, And MCP Strategy
+
+Root agent files are entry points, not guarantees.
+
+Durable memory lives in `docs/`.
+
+MCP is optional external context and does not override accepted repository memory.

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

@@ -0,0 +1,6 @@
+# MCP Strategy
+
+MCP is not required for this repository.
+
+If MCP is introduced later, document trusted servers, data accessed, permissions, risks, and
+source-of-truth rules.

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

@@ -0,0 +1,133 @@
+# Recall OS Commands
+
+This document records the Recall OS commands available to humans and AI agents.
+
+## Completion Gate
+
+Before claiming implementation work is complete, run:
+
+```txt
+pnpm test:run
+pnpm typecheck
+recall doctor
+```
+
+If `recall doctor` reports errors, fix them or report why they cannot be fixed. If it reports
+warnings, address them or record why they are acceptable.
+
+Package binary behavior is covered by binary integration tests.
+
+## Commands
+
+### `recall init`
+
+Initialize neutral repository memory.
+
+Options:
+
+- `--preset <id>`: apply optional preset guidance and proposed decisions.
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+- `--reinit`: required with `--force` to overwrite an existing Recall OS installation (a directory
+  that already has `.recall/config.json`). Without it, `--force` refuses, protecting existing
+  repository memory.
+
+Init also generates a tracked pre-commit hook at `.recall/hooks/pre-commit` that runs
+`recall doctor` plus any `preCommitGates` in `.recall/config.json`. Init proposes, but does not run,
+the activation command `git config core.hooksPath .recall/hooks`.
+
+### `recall adopt`
+
+Inspect an existing repository through read-only manifest and marker files, then write a proposed
+adoption report and proposed framework ADRs for human review. Adopt never executes repository code
+and never produces accepted memory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall skill create <name>`
+
+Generate a portable AI agent skill as `SKILL.md` for both Claude Code (`.claude/skills/`) and the
+portable Agent Skills target (`.agents/skills/`). Known names use the built-in catalog; unknown
+names produce a valid skeleton. Generated skills contain no scripts.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall skill list`
+
+List the built-in catalog skills.
+
+### `recall mcp add <server>`
+
+Generate offline, proposed memory for an MCP server (for example `figma`) as
+`docs/ai/mcp/<server>.md` plus a proposed adoption ADR. Recall OS never connects to the MCP server
+or makes network calls; the agent records durable MCP-derived context into the generated memory for
+human review. It also installs a `capture-mcp-context` agent skill that prompts the agent to record
+that context.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall preset list`
+
+List built-in presets.
+
+### `recall feature create <name>`
+
+Create feature memory docs under the configured features directory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall adr create <title>`
+
+Create a proposed ADR under the configured ADR directory.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall adr accept <name>`
+
+Promote a proposed ADR to accepted repository memory. A proposal under
+`docs/adrs/proposed/ADR-PROPOSED-<slug>.md` becomes a numbered, accepted `ADR-####-<slug>.md` and
+the proposal is removed; an existing numbered Proposed ADR is accepted in place.
+
+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.
+
+Options:
+
+- `--dry-run`: show planned writes without writing files.
+- `--force`: overwrite existing files explicitly.
+
+### `recall doctor`
+
+Check whether repository memory is structurally healthy enough for AI-assisted work, whether basic
+engineering evidence is present, and whether memory references decisions that exist and are
+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.
+
+Exit codes:
+
+- `0`: healthy
+- `1`: warnings only
+- `2`: errors

package/examples/generated-kotlin-android/docs/ai/presets/kotlin-android-guidance.md

@@ -0,0 +1,30 @@
+# Kotlin Android Preset Guidance
+
+This guidance is proposed, not accepted. Convert any choice you adopt into an accepted ADR in
+repository memory. Until then, treat everything here as a recommendation awaiting human review.
+
+## Decision forks this stack forces
+
+- UI toolkit: Jetpack Compose vs Android Views/XML.
+- Asynchrony: Kotlin Coroutines and Flow vs RxJava/callbacks.
+- Dependency injection: Hilt vs Koin vs manual.
+- Local persistence: Room vs SQLDelight vs DataStore.
+- Presentation pattern: MVVM vs MVI.
+
+## Recommended structure (proposed)
+
+- Feature-based modules or packages (`feature/`, `core/`, `data/`, `ui/`).
+- A repository layer between ViewModels and data sources.
+- Immutable UI state exposed as `StateFlow` from ViewModels.
+
+## Testing (proposed)
+
+- Unit tests with JUnit5 and coroutine test dispatchers.
+- Flow assertions with Turbine.
+- UI tests with Compose UI testing or Espresso.
+
+## Security considerations (proposed)
+
+- Store secrets with the Android Keystore, never in source or version control.
+- Use EncryptedSharedPreferences or DataStore with encryption for sensitive local data.
+- Enforce network security config and certificate pinning where appropriate.

package/examples/generated-nextjs/.recall/config.json

@@ -0,0 +1,17 @@
+{
+  "version": "0.1.0",
+  "templateVersion": "0.1.0",
+  "preset": "nextjs",
+  "memoryProfile": "standard",
+  "mode": "standard",
+  "aiTools": [
+    "claude",
+    "codex"
+  ],
+  "docsDir": "docs",
+  "featuresDir": "docs/40-features",
+  "modulesDir": "docs/30-modules",
+  "adrDir": "docs/adrs",
+  "writePolicy": "skip-existing",
+  "preCommitGates": []
+}

package/examples/generated-nextjs/.recall/hooks/pre-commit

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Recall OS pre-commit hook.
+# Generated by `recall init`. Edit gates in .recall/config.json (preCommitGates),
+# then re-run `recall init --force` to regenerate this hook.
+# Enable once per clone with:
+#   git config core.hooksPath .recall/hooks
+set -e
+
+recall doctor

package/examples/generated-nextjs/AGENTS.md

@@ -0,0 +1,15 @@
+# generated-nextjs Agent Instructions
+
+This repository uses Recall OS repository memory.
+
+Start with durable source-of-truth docs under `docs/`.
+
+Required reading:
+
+- `docs/00-product/PRD.md`
+- `docs/10-architecture/ARCHITECTURE.md`
+- `docs/20-security/SECURITY_MODEL.md`
+- `docs/50-quality/QUALITY_GATES.md`
+- `docs/60-engineering/ENGINEERING_STANDARDS.md`
+
+Repository rules override model preferences. If instructions conflict, stop and report the conflict.

package/examples/generated-nextjs/CLAUDE.md

@@ -0,0 +1,7 @@
+# generated-nextjs Claude Instructions
+
+Use this file as a short routing guide.
+
+The durable project memory lives in `docs/`. Do not rely on chat history as source of truth.
+
+Read `AGENTS.md` and the relevant docs before changing code or repository memory.

package/examples/generated-nextjs/README.md

@@ -0,0 +1,10 @@
+# Next.js Example
+
+This folder shows the repository memory generated by:
+
+```bash
+recall init --preset nextjs
+```
+
+The Next.js preset adds framework-aware guidance and proposed decisions. Those decisions remain
+proposed until a human accepts them in repository memory.