recall-os 0.1.0

package/examples/generated-python-fastapi/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-python-fastapi/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-python-fastapi/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-python-fastapi/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-python-fastapi/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-python-fastapi/docs/adrs/proposed/ADR-PROPOSED-python-fastapi-cache-redis.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Redis
+
+## Status
+
+Proposed
+
+## Context
+
+The service may need caching, rate limiting, or a task queue backend.
+
+## Decision
+
+Consider Redis for caching and background work, awaiting human acceptance.
+
+## Alternatives Considered
+
+- In-process caching only.
+- A managed queue service.
+
+## Consequences
+
+- Fast shared cache and queue backend.
+- Adds an operational dependency to run and monitor.

package/examples/generated-python-fastapi/docs/adrs/proposed/ADR-PROPOSED-python-fastapi-database-postgres.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use PostgreSQL with SQLAlchemy
+
+## Status
+
+Proposed
+
+## Context
+
+The service needs a relational database and a migration strategy.
+
+## Decision
+
+Consider PostgreSQL with SQLAlchemy and Alembic migrations, awaiting human acceptance.
+
+## Alternatives Considered
+
+- An async ORM such as Tortoise or SQLModel only.
+- Raw SQL with a lightweight driver.
+
+## Consequences
+
+- Mature tooling and explicit migrations.
+- Requires session and connection management discipline.

package/examples/generated-python-fastapi/docs/adrs/proposed/ADR-PROPOSED-python-fastapi-framework.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use FastAPI
+
+## Status
+
+Proposed
+
+## Context
+
+The service needs a Python web framework for an async API.
+
+## Decision
+
+Consider FastAPI as the web framework, awaiting human acceptance.
+
+## Alternatives Considered
+
+- Flask.
+- Django REST Framework.
+
+## Consequences
+
+- Async support and automatic OpenAPI docs.
+- Requires comfort with type hints and dependency injection.

package/examples/generated-python-fastapi/docs/adrs/proposed/ADR-PROPOSED-python-fastapi-testing-pytest.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use pytest
+
+## Status
+
+Proposed
+
+## Context
+
+The service needs a test framework and HTTP testing approach.
+
+## Decision
+
+Consider pytest with httpx for API tests, awaiting human acceptance.
+
+## Alternatives Considered
+
+- unittest.
+- nose-style runners.
+
+## Consequences
+
+- Concise fixtures and rich plugins.
+- Teams must standardize fixture and database setup.

package/examples/generated-python-fastapi/docs/adrs/proposed/ADR-PROPOSED-python-fastapi-validation-pydantic.md

@@ -0,0 +1,23 @@
+# Proposed ADR: Use Pydantic
+
+## Status
+
+Proposed
+
+## Context
+
+The service needs request validation and typed configuration.
+
+## Decision
+
+Consider Pydantic v2 models for validation and settings, awaiting human acceptance.
+
+## Alternatives Considered
+
+- Marshmallow.
+- Hand-written validation.
+
+## Consequences
+
+- Strong typing at the boundary and clear settings.
+- Adds Pydantic to the dependency surface.

package/examples/generated-python-fastapi/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-python-fastapi/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-python-fastapi/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-python-fastapi/docs/ai/presets/python-fastapi-guidance.md

@@ -0,0 +1,31 @@
+# Python FastAPI 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
+
+- Web framework: FastAPI vs Flask vs Django REST.
+- Database and access: PostgreSQL with SQLAlchemy and Alembic vs an async ORM vs raw SQL.
+- Validation and settings: Pydantic v2 models and settings.
+- Testing: pytest with httpx vs unittest.
+- Background work and caching: Redis, task queues, and async workers.
+
+## Recommended structure (proposed)
+
+- A layered layout: `api/` routers, `services/` logic, `repositories/` data access, `models/`
+  schemas.
+- Dependency injection through FastAPI dependencies.
+- Configuration via Pydantic settings loaded from environment variables.
+
+## Testing (proposed)
+
+- pytest with the FastAPI test client or httpx `AsyncClient`.
+- A disposable test database and transactional fixtures.
+- Contract tests for request and response schemas.
+
+## Security considerations (proposed)
+
+- Load secrets from environment or a secret manager, never from source.
+- Validate and constrain all input with Pydantic models.
+- Scope authentication and authorization at the dependency layer.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "recall-os",
+  "version": "0.1.0",
+  "description": "Architecture-neutral repository memory for AI-assisted software teams.",
+  "packageManager": "pnpm@10.12.3",
+  "type": "module",
+  "license": "MIT",
+  "author": "Karthick Ramachandran",
+  "homepage": "https://github.com/Karthick-Ramachandran/recall-os#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Karthick-Ramachandran/recall-os.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Karthick-Ramachandran/recall-os/issues"
+  },
+  "keywords": [
+    "repository-memory",
+    "engineering-memory",
+    "adr",
+    "architecture-decision-records",
+    "ai-agents",
+    "agent-skills",
+    "governance",
+    "drift-detection",
+    "cli",
+    "local-first"
+  ],
+  "bin": {
+    "recall": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "examples"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "eslint .",
+    "format:check": "prettier --check \"*.json\" \"*.js\" \"*.ts\" \".github/**/*.yml\" \"src/**/*.ts\" \"tests/**/*.ts\" \"scripts/**/*.mjs\" \"README.md\" \"examples/**/*.md\" \"docs/40-features/F-013-recall-os-package-release/**/*.md\" \"docs/30-modules/package-release/**/*.md\"",
+    "pack:check": "node scripts/check-package.mjs",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm build && pnpm pack:check"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.0.0",
+    "eslint": "^10.5.0",
+    "prettier": "^3.8.4",
+    "tsup": "^8.5.1",
+    "typescript": "^5.8.0",
+    "typescript-eslint": "^8.61.1",
+    "vitest": "^3.2.0"
+  },
+  "dependencies": {
+    "commander": "^15.0.0",
+    "zod": "^4.4.3"
+  }
+}