chore(openspec): archive engineering-docs and phase-2-production-ready changes

- engineering-docs → archive/2026-03-29-engineering-docs (63/63 tasks complete)
- phase-2-production-ready → archive/2026-03-29-phase-2-production-ready (89/89 tasks complete)
- openspec/specs/ synced with all Phase 1 + Phase 2 + engineering-docs capabilities (22 specs total)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/archive/2026-03-29-engineering-docs/design.md

@@ -0,0 +1,105 @@
+## Context
+
+SentryAgent.ai has completed Phase 1 (MVP) and Phase 2 (Production-Ready), producing a fully implemented AgentIdP with 12 capabilities across ~150 source files, 4 language SDKs, Terraform infrastructure, and a React web dashboard. The codebase is mature but undocumented at the engineering level — there are bedroom developer guides (`docs/developers/`) and DevOps guides (`docs/devops/`), but no structured internal engineering knowledge base.
+
+New hires arrive with BSc Computer Science and one year of industrial experience. They understand programming fundamentals and have worked on codebases before, but they have no context on: what SentryAgent.ai is building, why architectural decisions were made, how the codebase is structured, how to navigate the services, how to contribute per our standards, or how the OpenSpec workflow operates. Without documentation, onboarding is fragmented and relies entirely on the CTO's time.
+
+The goal is a `docs/engineering/` directory that a new engineer can read sequentially from top to bottom and arrive ready to contribute within their first week.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Produce a complete top-down engineering knowledge base readable in sequence
+- Cover all 10 capability areas identified in the proposal
+- Calibrate depth for BSc + 1yr experience — assume programming competence, explain domain and architectural decisions
+- Every document is self-contained with internal cross-links where needed
+- All code examples are complete and runnable (no ellipses, no `// ... rest of code`)
+- Development environment setup is achievable in under 30 minutes following the guide alone
+- Annotated walkthroughs trace the three critical flows through every layer of code with file:line references
+
+**Non-Goals:**
+- Not a replacement for `docs/developers/` (end-user API reference) or `docs/devops/` (operator runbooks)
+- Not a tutorial for learning TypeScript, React, or Terraform — assumes language competence
+- Not a complete API reference — `docs/developers/api-reference.md` already covers that
+- Not roadmap documentation — focuses on what is built, not what is planned
+
+## Decisions
+
+### D1: Location — `docs/engineering/` as a flat directory with an index
+
+**Decision**: All engineering docs live in `docs/engineering/` as flat markdown files with a `README.md` index.
+
+**Rationale**: Deep nested directory structures create navigation friction. Flat layout with numbered filenames (`01-overview.md`, `02-architecture.md`) ensures reading order is obvious without needing a build tool. Gitea renders markdown natively, so no documentation site tooling is required.
+
+**Alternatives considered**:
+- `docs/engineering/<subdirs>/` — rejected: adds navigation complexity with no benefit at our current document count
+- Docusaurus site — rejected: adds build infrastructure overhead; plain markdown in-repo is sufficient and always in sync with code
+
+---
+
+### D2: Numbered file naming for enforced reading order
+
+**Decision**: Files are named `01-overview.md` through `10-sdk-guide.md`.
+
+**Rationale**: New engineers need a guided path, not a reference library. Numbers make the intended reading sequence unambiguous without any tooling. The `README.md` index maps numbers to sections.
+
+---
+
+### D3: Annotated walkthroughs use file:line references
+
+**Decision**: Code walkthrough documents reference actual source files with line numbers (e.g., `src/controllers/agentController.ts:45`).
+
+**Rationale**: Engineers with 1yr experience learn fastest by reading real code, not simplified pseudocode. File:line references let them jump directly to the relevant section in their editor or on Gitea.
+
+**Trade-off**: Line numbers drift as code changes. Mitigation: walkthrough documents include a "last verified" version comment and note which commit they were verified against. The CTO adds walkthrough review to the Phase 3 change process as a maintenance item.
+
+---
+
+### D4: Three walkthroughs selected by criticality and complexity
+
+**Decision**: Walkthroughs cover: (1) OAuth 2.0 token issuance, (2) agent registration, (3) credential rotation.
+
+**Rationale**:
+- Token issuance is the highest-traffic path and touches the most layers (controller → service → repository → Redis → JWT signing)
+- Agent registration is the entry point for all users and demonstrates the full validation + persistence + audit pattern
+- Credential rotation demonstrates the Vault integration path and shows how Phase 2 extended Phase 1 patterns
+
+These three flows collectively exercise every architectural layer and every major design pattern in the codebase.
+
+---
+
+### D5: Service deep-dives use a consistent template
+
+**Decision**: Each service deep-dive follows the structure: Purpose → Responsibility boundary → Interface → Key methods → Database schema (if applicable) → Error types → Configuration.
+
+**Rationale**: Consistency reduces cognitive load. An engineer who has read the AgentService deep-dive knows exactly where to look for the same information in the OAuth2Service deep-dive. The template mirrors SOLID's Single Responsibility — each section answers one question.
+
+---
+
+### D6: Engineering workflow doc is prescriptive, not descriptive
+
+**Decision**: The workflow guide tells engineers exactly what to do step by step, not just what the process is.
+
+**Rationale**: Engineers with 1yr experience have worked in teams but may not have used a spec-first workflow before. A prescriptive guide ("Step 1: run `openspec new change <name>`") reduces ambiguity and enforces our standards from day one.
+
+## Risks / Trade-offs
+
+**[Line numbers drift as code evolves]** → Walkthroughs include a "last verified against commit X" header. The CTO assigns a quarterly walkthrough review task in each Phase change.
+
+**[Docs can become stale if not maintained]** → Each document has a "Last updated" field in its header. The engineering workflow guide explicitly requires updating relevant engineering docs as part of any PR that changes architecture or public service interfaces.
+
+**[Scope is large — ~15 documents, ~10,000 lines]** → Tasks are broken into discrete documents, each independently completable. No document depends on another being written first (only the index depends on all others).
+
+## Migration Plan
+
+1. Create `docs/engineering/` directory
+2. Write all 15 documents (10 capability areas, some split across multiple files)
+3. Write `docs/engineering/README.md` index with links and reading order
+4. Commit all to `develop` in a single commit
+5. No existing documentation is modified or removed
+
+No rollback required — this is additive only.
+
+## Open Questions
+
+_(none — all decisions made above; scope fully defined in proposal)_