arkaos 2.0.0-alpha.1

package/departments/dev/skills/ai-security/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: dev/ai-security
+description: >
+  AI/ML-specific security assessment: prompt injection, model poisoning,
+  data leakage, agent tool abuse, and MITRE ATLAS technique mapping.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# AI Security — `/dev ai-security`
+
+> **Agent:** Bruno (Security Engineer) | **Framework:** OWASP ML Top 10, NIST AI RMF, MITRE ATLAS
+
+## Threat Categories
+
+| Threat | Severity | ATLAS ID | What to Check |
+|--------|----------|----------|--------------|
+| Direct prompt injection | Critical | AML.T0051 | System-prompt overrides, role replacement |
+| Indirect injection (RAG) | Critical | AML.T0051.001 | Malicious content in retrieved documents |
+| Jailbreak (persona) | High | AML.T0051 | "DAN mode", "developer mode", persona bypass |
+| System prompt extraction | High | AML.T0056 | "Repeat your instructions", "Show system prompt" |
+| Agent tool abuse | Critical | AML.T0051.002 | "Call delete_files", "Bypass approval check" |
+| Data poisoning | High | AML.T0020 | Malicious training examples, backdoor triggers |
+| Model inversion | High | AML.T0024 | Training data reconstruction from outputs |
+
+## Model Inversion Risk by Access Level
+
+| Access | Risk | Attack | Mitigation |
+|--------|------|--------|-----------|
+| White-box | Critical (0.9) | Gradient-based inversion | Remove gradient access in prod; differential privacy |
+| Gray-box | High (0.6) | Confidence-based inference | Disable logit outputs; rate limit API |
+| Black-box | Low (0.3) | Label-only, high query volume | Monitor for systematic querying patterns |
+
+## Data Poisoning Risk by Scope
+
+| Scope | Risk | Mitigation |
+|-------|------|-----------|
+| Fine-tuning | High (0.85) | Audit all training examples; data provenance |
+| RLHF | High (0.70) | Vet feedback contributors |
+| RAG / retrieval | Medium (0.60) | Validate content before indexing |
+| Pre-trained only | Low (0.20) | Verify model provenance; trusted sources |
+| Inference only | Low (0.10) | Standard input validation |
+
+## Guardrail Design Checklist
+
+### Input Guardrails (before inference)
+- [ ] Injection signature filter (regex against known patterns)
+- [ ] Input length limit (prevent many-shot / context stuffing)
+- [ ] Content policy classifier (separate from main model)
+- [ ] External content treated as untrusted (RAG, web, email, API)
+
+### Output Guardrails (after inference)
+- [ ] System prompt confidentiality (detect/redact leakage)
+- [ ] PII detection (email, SSN, credit card patterns)
+- [ ] URL and code validation before display
+
+### Agent Guardrails (tool access)
+- [ ] Human approval gates for destructive actions (delete, send, upload)
+- [ ] Minimal tool scope (only what the task needs)
+- [ ] Tool parameter validation before execution
+- [ ] Audit logging of every tool call with prompt context
+
+## Assessment Workflow
+
+| Step | Action | Output |
+|------|--------|--------|
+| 1 | Identify AI components | Inventory: models, agents, RAG, tools |
+| 2 | Classify access level | Black-box / gray-box / white-box per component |
+| 3 | Run injection scan | Injection score (0.0-1.0) per component |
+| 4 | Assess model risks | Inversion + poisoning risk scores |
+| 5 | Review guardrails | Checklist pass/fail per layer |
+| 6 | Map to ATLAS | Technique coverage and gaps |
+| 7 | Recommend controls | Prioritized by risk score |
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Fails |
+|-------------|-------------|
+| Testing only known jailbreaks | Published templates already blocked; test domain-specific |
+| Static signatures only | Novel attacks bypass regex; add semantic similarity |
+| Ignoring indirect injection | RAG content is higher risk than direct user input |
+| No output filtering | Successful injection produces malicious output regardless |
+| Skipping prod system prompt | Jailbreaks that fail in isolation may succeed with real prompt |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- LLM with unrestricted tool access → CRITICAL flag
+- No output filtering on AI responses → flag data leakage
+- Training data containing PII → flag privacy violation
+
+## Output
+
+```markdown
+## AI Security Assessment: <System>
+
+### Component Inventory
+| Component | Type | Access Level | Risk Score |
+|-----------|------|-------------|------------|
+
+### Findings
+| # | Threat | Severity | ATLAS ID | Component |
+|---|--------|----------|----------|-----------|
+
+### Guardrail Status
+| Layer | Control | Status | Gap |
+|-------|---------|--------|-----|
+
+### Recommendations
+| Priority | Action | Effort | Risk Reduced |
+|----------|--------|--------|-------------|
+```

package/departments/dev/skills/api-design/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: dev/api-design
+description: >
+  Design REST or GraphQL APIs with versioning, documentation, and contracts.
+  Follows OpenAPI spec for REST, SDL for GraphQL.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# API Design — `/dev api-design <api>`
+
+> **Agent:** Gabriel (Architect) + Andre (Backend)
+> **Output:** OpenAPI spec or GraphQL SDL + endpoint documentation
+
+## REST API Design Principles
+
+1. **Resource-oriented** — URLs are nouns, not verbs (`/users`, not `/getUsers`)
+2. **HTTP methods** — GET (read), POST (create), PUT (replace), PATCH (update), DELETE
+3. **Status codes** — 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 422 Unprocessable
+4. **Pagination** — `?page=1&per_page=20` with Link headers or cursor-based
+5. **Filtering** — `?status=active&role=admin`
+6. **Versioning** — URL prefix (`/api/v1/`) or header (`Accept: application/vnd.api+json;version=1`)
+7. **Consistent response** — `{ "data": ..., "meta": { "pagination": ... } }`
+8. **Error format** — `{ "error": { "code": "VALIDATION_FAILED", "message": "...", "details": [...] } }`
+
+## Output: OpenAPI Snippet
+
+```yaml
+openapi: 3.0.3
+info:
+  title: <API Name>
+  version: 1.0.0
+paths:
+  /api/v1/<resource>:
+    get:
+      summary: List <resources>
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, default: 1 }
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items: { $ref: '#/components/schemas/<Resource>' }
+```
+
+## Laravel Convention
+
+- Routes: `routes/api.php` with `apiResource()`
+- Controllers: `App\Http\Controllers\Api\V1\<Resource>Controller`
+- Requests: `App\Http\Requests\<Resource>\Store<Resource>Request`
+- Resources: `App\Http\Resources\<Resource>Resource`
+- Tests: `tests/Feature/Api/V1/<Resource>Test.php`

package/departments/dev/skills/architecture-design/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: dev/architecture-design
+description: >
+  Design system architecture using Clean Architecture, Hexagonal, or DDD patterns.
+  Produces an ADR (Architecture Decision Record) saved to Obsidian.
+allowed-tools: [Read, Write, Edit, Grep, Glob, Agent, WebFetch]
+---
+
+# Architecture Design — `/dev architecture <system>`
+
+> **Agent:** Gabriel (Architect) | **Approver:** Marco (CTO)
+> **Frameworks:** Clean Architecture, Hexagonal, DDD, Vertical Slice
+
+## Workflow
+
+### Step 1: Context Loading
+- Read PROJECT.md and existing architecture
+- Scan current codebase structure
+- Identify existing patterns and conventions
+
+### Step 2: Requirements Gathering
+- Ask user: What system/feature needs architecture?
+- Clarify: Scale requirements, team size, tech constraints
+- Identify: Domain boundaries, data flows, external integrations
+
+### Step 3: Architecture Design
+Apply the appropriate pattern:
+
+**Clean Architecture** (default for most systems):
+```
+Domain (entities, value objects) → no dependencies
+Application (use cases) → depends on Domain
+Interface Adapters (controllers, gateways) → depends on Application
+Frameworks (DB, HTTP, UI) → depends on Interface Adapters
+```
+
+**Hexagonal** (when many external integrations):
+```
+Ports (interfaces defined by domain)
+Adapters (implementations for each external system)
+```
+
+**DDD Strategic** (when complex domain):
+```
+Bounded Contexts → Context Map → Aggregates → Domain Events
+```
+
+### Step 4: ADR Document
+
+```markdown
+---
+type: adr
+title: "ADR-NNN: <Decision Title>"
+status: proposed
+date: YYYY-MM-DD
+tags: [architecture, <domain>]
+---
+
+# ADR-NNN: <Decision Title>
+
+## Context
+What is the situation that requires a decision?
+
+## Decision
+What is the architecture we chose?
+
+## Alternatives Considered
+What else did we consider and why did we reject it?
+
+## Data Flow
+How does data move through the system?
+
+## API Contracts
+Key interfaces between components.
+
+## Schema Changes
+Database changes needed.
+
+## Consequences
+What are the trade-offs of this decision?
+
+## Security Considerations
+Security implications and mitigations.
+```
+
+### Step 5: CTO Review
+- Marco reviews the ADR
+- Approves or requests changes
+- ADR saved to Obsidian: `Projects/<name>/Architecture/ADR-<NNN>.md`

package/departments/dev/skills/changelog/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: dev/changelog
+description: >
+  Generate changelogs from git history using conventional commits. Lint commit messages, detect version bumps, and render Keep a Changelog format.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Changelog Generator — `/dev changelog`
+
+> **Agent:** Andre (Senior Backend Dev) | **Framework:** Keep a Changelog, Conventional Commits, SemVer
+
+## Conventional Commit Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+| Type | Changelog Section | SemVer Bump |
+|------|------------------|-------------|
+| `feat` | Added | MINOR |
+| `fix` | Fixed | PATCH |
+| `perf` | Changed | PATCH |
+| `security` | Security | PATCH |
+| `refactor` | Changed | -- |
+| `docs` | -- (internal) | -- |
+| `test` | -- (internal) | -- |
+| `chore` | -- (internal) | -- |
+| `feat!` / `BREAKING CHANGE:` | Breaking Changes | MAJOR |
+| `deprecated` | Deprecated | -- |
+| `remove` | Removed | MAJOR |
+
+## Generation Workflow
+
+1. **Determine range** -- Last tag to HEAD (or tag-to-tag)
+   ```bash
+   git log v1.3.0..HEAD --pretty=format:"%s" --no-merges
+   ```
+
+2. **Parse commits** -- Extract type, scope, description, breaking changes
+
+3. **Detect version bump** -- Highest priority: MAJOR > MINOR > PATCH
+
+4. **Group by section** -- Map commit types to Keep a Changelog sections
+
+5. **Render changelog** -- Prepend new entry to CHANGELOG.md
+
+## Quality Rules
+
+| Rule | Rationale |
+|------|-----------|
+| Every bullet must be user-meaningful | No "fix typo in test" in release notes |
+| Breaking changes include migration steps | Users need actionable guidance |
+| Security fixes in dedicated section | Visibility for security-conscious users |
+| Empty sections are omitted | Clean, scannable output |
+| Duplicate bullets are removed | One entry per change |
+| Scope shown for multi-package repos | `auth: add OAuth2 support` |
+
+## Commit Linting Checklist
+
+- [ ] Commit starts with valid type (`feat`, `fix`, `perf`, etc.)
+- [ ] Description is lowercase, imperative mood, < 72 chars
+- [ ] Scope matches known modules (if enforced)
+- [ ] Breaking changes use `!` suffix or `BREAKING CHANGE:` footer
+- [ ] No merge commits in changelog range
+
+## Monorepo Strategy
+
+- Filter commits by scope for package-specific changelogs
+- Keep infrastructure changes in root CHANGELOG.md
+- Store package changelogs at package root
+- Use scoped commits: `feat(api): add pagination endpoint`
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- >20 commits without changelog update → flag documentation drift
+- Non-conventional commit messages → flag automation breakage
+- No changelog entry for breaking changes → flag user communication gap
+
+## Output
+
+```markdown
+# Changelog
+
+## [X.Y.Z] - YYYY-MM-DD
+
+### Breaking Changes
+- **scope:** Description of breaking change
+  Migration: [steps to migrate]
+
+### Added
+- **scope:** New feature description (#PR)
+
+### Fixed
+- **scope:** Bug fix description (#PR)
+
+### Changed
+- **scope:** Change description (#PR)
+
+### Security
+- **scope:** Security fix description (#PR)
+
+### Deprecated
+- **scope:** Deprecation notice and timeline
+```

package/departments/dev/skills/ci-cd-pipeline/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: dev/ci-cd-pipeline
+description: >
+  Design and generate CI/CD pipelines from detected project stack.
+  GitHub Actions and GitLab CI with caching, matrix builds, and deployment gates.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent]
+---
+
+# CI/CD Pipeline — `/dev ci-cd-pipeline <project>`
+
+> **Agent:** Andre (Backend Dev) | **Framework:** DevOps Pipeline Design
+
+## What This Does
+
+Detects project stack from repository files, then generates pragmatic CI/CD pipelines with lint, test, build, and deploy stages. Supports GitHub Actions and GitLab CI.
+
+## Stack Detection Heuristics
+
+| Signal | Determines |
+|--------|-----------|
+| Lockfiles (`composer.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) | Package manager |
+| Manifests (`composer.json`, `package.json`, `pyproject.toml`, `go.mod`) | Runtime/language |
+| Script commands in manifests | Lint, test, build commands |
+| Missing scripts | Conservative placeholder commands |
+
+## Pipeline Stages
+
+| Stage | Purpose | Gate |
+|-------|---------|------|
+| **Lint** | Code style, static analysis | Must pass before test |
+| **Test** | Unit + feature tests | Must pass before build |
+| **Build** | Compile, bundle, optimize | Must pass before deploy |
+| **Deploy (staging)** | Deploy to staging environment | Explicit environment context |
+| **Deploy (production)** | Deploy to production | Manual approval gate required |
+
+## Platform Selection
+
+| Platform | When to Choose |
+|----------|---------------|
+| **GitHub Actions** | Tight GitHub ecosystem, public repos, most teams |
+| **GitLab CI** | Self-hosted SCM + CI, integrated container registry |
+
+Keep one canonical pipeline source per repo to reduce drift.
+
+## Caching Strategy by Stack
+
+| Stack | Cache Key | Cache Path |
+|-------|-----------|-----------|
+| **Node.js (npm)** | `${{ hashFiles('package-lock.json') }}` | `~/.npm` |
+| **Node.js (pnpm)** | `${{ hashFiles('pnpm-lock.yaml') }}` | `~/.pnpm-store` |
+| **PHP (Composer)** | `${{ hashFiles('composer.lock') }}` | `vendor/` |
+| **Python (pip)** | `${{ hashFiles('requirements.txt') }}` | `~/.cache/pip` |
+| **Go** | `${{ hashFiles('go.sum') }}` | `~/go/pkg/mod` |
+
+## Design Checklist
+
+- [ ] Stack detected from lockfiles and manifests
+- [ ] Lint, test, build commands verified to exist in project
+- [ ] Cache strategy matches package manager
+- [ ] Required secrets documented (not embedded in YAML)
+- [ ] Branch protection rules match org policy
+- [ ] Deploy jobs gated by protected environments
+- [ ] Matrix builds only when compatibility truly requires it
+- [ ] Pipeline duration tracked as a metric
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+|---------|-----|
+| Copying a Node pipeline into Python/Go repos | Detect stack first, then generate |
+| Deploy jobs before stable tests | Require green CI before deploy |
+| Forgetting dependency cache keys | Use lockfile hash as cache key |
+| Expensive matrix builds on every branch | Limit matrix to main/release branches |
+| Hardcoded secrets in YAML | Use CI secret store, document required vars |
+| No rollback plan | Keep rollout/rollback commands explicit |
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- No caching in CI → flag slow pipeline
+- Deploy without smoke test → flag blind deployment
+- Secrets in env vars without rotation → flag security risk
+
+## Output
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: <setup-action>
+      - run: <install-command>
+      - run: <lint-command>
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: <setup-action>
+      - run: <install-command>
+      - run: <test-command>
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: <setup-action>
+      - run: <install-command>
+      - run: <build-command>
+
+  deploy:
+    needs: build
+    if: github.ref == 'refs/heads/main'
+    environment: <staging|production>
+    runs-on: ubuntu-latest
+    steps:
+      - run: <deploy-command>
+```

package/departments/dev/skills/clean-code-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: dev/clean-code-review
+description: >
+  Review code against Clean Code (Uncle Bob) and SOLID principles. Checks naming,
+  function size, nesting depth, dead code, god classes, and dependency direction.
+allowed-tools: [Read, Grep, Glob, Agent]
+---
+
+# Clean Code Review — `/dev clean-review <file>`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** Clean Code + SOLID (Robert C. Martin)
+
+## What It Does
+
+Reviews a file or PR against Clean Code and SOLID principles. Returns a structured
+report with issues categorized as BLOCKER, WARNING, or NOTE.
+
+## Checklist
+
+### Clean Code Checks
+- [ ] **Meaningful names** — Variables, functions, classes reveal intent
+- [ ] **Small functions** — Under 30 lines, one responsibility each
+- [ ] **Max 3 nesting levels** — No arrow code
+- [ ] **Max 3 parameters** — Use objects for more
+- [ ] **No dead code** — Remove commented-out code, unused imports
+- [ ] **No magic numbers** — Named constants instead
+- [ ] **Command-Query Separation** — Functions either do something or return something
+- [ ] **DRY** — No duplicated logic (3+ lines repeated = extract)
+- [ ] **Self-documenting** — Code readable without comments explaining the "what"
+
+### SOLID Checks
+- [ ] **SRP** — Each class has one reason to change
+- [ ] **OCP** — Extend via interfaces/abstractions, not modification
+- [ ] **LSP** — Subtypes are substitutable for their base types
+- [ ] **ISP** — No client depends on methods it doesn't use
+- [ ] **DIP** — High-level modules depend on abstractions, not details
+
+### Architecture Checks
+- [ ] **Dependency Rule** — Dependencies point inward (domain doesn't import framework)
+- [ ] **No business logic in controllers** — Controllers delegate to services
+- [ ] **Repository pattern** — Data access abstracted from business logic
+
+## Output Format
+
+```markdown
+## Clean Code Review: <file>
+
+### BLOCKERS (must fix)
+- [B1] `ClassName:lineN` — God class with 15 methods and 4 responsibilities
+  Fix: Split into UserService, AuthService, NotificationService
+
+### WARNINGS (should fix)
+- [W1] `functionName:lineN` — Function is 45 lines (max: 30)
+  Fix: Extract validation logic into validateInput()
+
+### NOTES (nice to have)
+- [N1] `variableName:lineN` — Name could be more descriptive
+  Suggest: `userAccountBalance` instead of `bal`
+
+### Summary
+- SOLID score: 4/5 (ISP violation in UserInterface)
+- Clean Code score: 7/10
+- Nesting max: 2 (good)
+- Longest function: 45 lines (needs split)
+```

package/departments/dev/skills/code-review/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: dev/code-review
+description: >
+  Code review against Clean Code and SOLID. Checks naming, SRP, DIP, test coverage, security.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# Code Review — `/dev review <file/pr>`
+
+> **Agent:** Paulo (Tech Lead) | **Framework:** Clean Code + SOLID (Uncle Bob)
+
+## What It Does
+
+Code review against Clean Code and SOLID. Checks naming, SRP, DIP, test coverage, security.
+
+## Output
+
+Review report: BLOCKER/WARNING/NOTE with line references and fix suggestions

package/departments/dev/skills/codebase-onboard/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: dev/codebase-onboard
+description: >
+  Analyze an existing codebase and generate onboarding documentation: architecture, patterns, setup, key files.
+allowed-tools: [Read, Bash, Grep, Glob, Agent]
+---
+
+# Codebase Onboarding — `/dev codebase-onboard`
+
+> **Agent:** Paulo (Dev Lead) | **Framework:** Developer Experience, Architecture Documentation
+
+## What It Does
+
+Analyzes an existing codebase to generate onboarding documentation. Maps architecture, identifies patterns, documents setup, and highlights key files a new developer needs to understand.
+
+## Analysis Steps
+
+| Step | What to Discover | How |
+|------|-----------------|-----|
+| 1. Stack Detection | Languages, frameworks, versions | `package.json`, `composer.json`, `pyproject.toml`, `Gemfile` |
+| 2. Structure Map | Directory layout, entry points | Top-level dirs, `src/`, `app/`, config files |
+| 3. Architecture | Patterns (MVC, DDD, microservices) | Folder naming, dependency injection, service layers |
+| 4. Data Layer | Database, ORM, migrations | Schema files, models, migration history |
+| 5. API Surface | Routes, controllers, endpoints | Route files, OpenAPI specs, Postman collections |
+| 6. Testing | Test framework, coverage, conventions | Test dirs, config files, CI test steps |
+| 7. DevOps | CI/CD, Docker, deployment | `.github/workflows/`, `Dockerfile`, deploy configs |
+| 8. Key Files | Config, env, entry points | `.env.example`, main configs, bootstrap files |
+
+## Audience Depth
+
+| Audience | Focus | Skip |
+|----------|-------|------|
+| Junior Dev | Setup + guardrails + common tasks | Deep architecture rationale |
+| Senior Dev | Architecture + patterns + operational concerns | Basic setup details |
+| Contractor | Scoped ownership + integration boundaries | Internal team processes |
+
+## Codebase Signals to Detect
+
+| Signal | Files | Indicates |
+|--------|-------|-----------|
+| Laravel | `artisan`, `composer.json` (laravel/framework) | PHP backend, Eloquent ORM |
+| Nuxt/Vue | `nuxt.config.ts`, `vue.config.js` | Vue frontend, SSR capable |
+| Next.js | `next.config.js`, `app/` directory | React frontend, App Router |
+| Docker | `Dockerfile`, `docker-compose.yml` | Containerized deployment |
+| Monorepo | `turbo.json`, `nx.json`, `pnpm-workspace.yaml` | Multi-package workspace |
+
+## Quality Checklist
+
+- [ ] Setup instructions tested on clean environment
+- [ ] All commands are copy-pasteable and time-bounded
+- [ ] Architecture decisions documented with "why" not just "what"
+- [ ] Key files listed with purpose explanation
+- [ ] Common tasks documented (run tests, add feature, deploy)
+- [ ] Troubleshooting section covers known gotchas
+
+## Proactive Triggers
+
+Surface these issues WITHOUT being asked:
+
+- No README or outdated README → flag onboarding barrier
+- No local dev setup instructions → flag contributor friction
+- Missing architecture diagram → flag understanding gap
+
+## Output
+
+```markdown
+## Codebase Onboarding: <project-name>
+
+### Stack
+- **Backend:** Laravel 11 / PHP 8.3
+- **Frontend:** Nuxt 3 / Vue 3 / TypeScript
+- **Database:** PostgreSQL 16, Redis 7
+- **Infrastructure:** Docker, GitHub Actions, AWS
+
+### Architecture Overview
+- Pattern: Service-Repository (thin controllers)
+- Auth: Laravel Sanctum (SPA + API tokens)
+- Queue: Redis-backed, Horizon dashboard
+
+### Key Files
+| File | Purpose |
+|------|---------|
+| `routes/api.php` | All API route definitions |
+| `app/Services/` | Business logic layer |
+| `app/Http/Requests/` | Form validation |
+| `.env.example` | Required environment variables |
+
+### Local Setup (estimated: 15 minutes)
+1. `git clone <repo> && cd <project>`
+2. `cp .env.example .env`
+3. `composer install && npm install`
+4. `php artisan key:generate`
+5. `php artisan migrate --seed`
+6. `npm run dev` (Vite dev server)
+   Verify: `http://localhost:8000` loads
+
+### Common Tasks
+| Task | Command |
+|------|---------|
+| Run tests | `php artisan test` |
+| Add migration | `php artisan make:migration` |
+| Queue worker | `php artisan horizon` |
+| Fresh seed | `php artisan migrate:fresh --seed` |
+
+### Gotchas
+- Redis must be running for queue/cache
+- `.env` DB_HOST differs between Docker and Herd
+- Run `npm run build` before testing SSR locally
+```