# Codebase Cleanup

> Full audit: 2026-04-04 · Every file reviewed

---

## ✅ DONE

### Deleted

| Item | Reason |
|------|--------|
| `claude.md` | 405-line monolith, superseded by `.claude/claude.md` + `.agents/skills/` |
| `docs/mockups/` | Stale HTML mockup |
| `docs/getting-started.md` | Replaced by `docs/quickstart.md` |
| `docs/user-guide.md` | Replaced by `docs/guide.md` |
| `docs/configuration.md` | `.env.example` is source of truth |
| `docs/architecture.md` | Overlaps with `internal/architecture/mindmap.md` |
| `docs/api-reference.md` | Use FastAPI auto-docs at `/docs` |
| `mockups/app/` | 3 stale HTML mockups |
| `internal/architecture/er_diagram.md` | Backend generates ER dynamically |
| `internal/specs/` | Directory removed — see below |
| `internal/specs/technical/TECHNICAL_SPEC.md` | 1029-line pre-implementation fantasy (Next.js, pgvector, AWS Terraform — none exist) |
| `internal/specs/technical/UI_MOCKUP_SPEC.md` | Old "Google Antigravity" design system |
| `internal/specs/technical/DESIGN_SYSTEM.md` | Superseded by shadcn + `.agents/skills/` |
| `internal/specs/features/MOCKUP_APPROVAL_WORKFLOW.md` | Already implemented |
| `internal/specs/features/CHECKPOINT_SYSTEM_SPEC.md` | Superseded by LangGraph proposal |
| `internal/architecture/thoughts.md` | 286 lines of raw brainstorming. Absorbed into `proposals/done/proposal-multi-agent-pipeline.md` |

### Moved

| Item | Destination | Reason |
|------|-------------|--------|
| `docs/sdlc-architecture-plan.md` | `proposals/pending/` | Internal, not user-facing. Not yet implemented |
| `docs/code-subtabs.md` | `proposals/done/implementation-code-subtabs.md` | Internal component docs. Already built |
| `internal/specs/features/BRANDING_LANDING_SPEC.md` | `proposals/pending/` | Feature spec → proposal |
| `internal/specs/features/GITHUB_INTEGRATION_SPEC.md` | `proposals/pending/` | Feature spec → proposal |
| `internal/specs/features/TEMPLATE_SYSTEM_SPEC.md` | `proposals/pending/` | Feature spec → proposal |
| `internal/research/initial.md` | `architecture/initial-research.md` | Historical context, renamed for clarity |

### Updated

| Item | What changed |
|------|-------------|
| `.claude/claude.md` | Fixed paths, added proposals/, 12-factor, skills refs |
| `.claude/agent.md` | Added blueprint-generator agent, fixed planned agents |
| `.claude/skills.md` | Replaced venv/pip with `./build.sh`, added `/logs` |
| `.claude/plans/MASTER_PLAN.md` | v0.1.0 = 1.0.0-beta, future scale v0.2→v1.0, AuthLib, correct scope |

### Created

| Item | Purpose |
|------|--------|
| `docs/quickstart.md` | SaaS user onboarding (sign up, BYOLLM, first project) |
| `docs/guide.md` | Product walkthrough with approval gates |

---

## 🗑️ DELETE — Stale, Redundant, or Superseded

### Deleted

| File | Verdict | Reason |
|------|---------|--------|
| `frontend/SKILL.md` | ✅ Deleted | Empty stub. Real skills in `.agents/skills/` |
| `internal/SETUP.md` | ✅ Deleted | Outdated setup guide, replaced by README + `.env.example` |
| `internal/VERIFICATION_GUIDE.md` | ✅ Deleted | Old API testing guide referencing dead endpoints |
| `internal/architecture/thoughts.md` | ✅ Deleted | Absorbed into `proposals/done/proposal-multi-agent-pipeline.md` |

### Kept (reclassified)

| File | Why keeping |
|------|-------------|
| `internal/IDEA_VALIDATION.md` | Actively maintained — re-validated this session (8.9/10 score) |
| `internal/ai-rescue.md` | NerdAppLabs reference — not app.xyz code, but kept for cross-project context |

---

## ✅ KEEP — Active and Relevant

### Root
| File | Why |
|------|-----|
| `README.md` | ✅ Updated — v0.1.0 scope + "Spec it. See it. Ship it." |
| `.env.example` | ✅ Config source of truth — comprehensive, well-commented |
| `docker-compose.yml` | ✅ Active infrastructure definition |
| `build.sh` | ✅ Active build tooling |
| `mockups/factory/landing.html` | ✅ Kept per request |

### `internal/` — Core reference
| File | Lines | Why keep |
|------|-------|---------|
| `v0.1.0.md` | 77 | **Launch scope** — defines what's in/out for v0.1.0 |
| `launch-copy.md` | 171 | **Positioning bible** — taglines, competitive framing, PH copy, tweets |
| `12-factor-audit.md` | 159 | **Production readiness** — gap analysis with specific fixes |
| `LLM_CONFIGURATION.md` | 278 | **BYOLLM reference** — per-use-case config, provider comparison |
| `BLOG_STRATEGY.md` | 219 | **Content playbook** — calendar, SEO targets, cross-sell paths |
| `GO_TO_MARKET_PLAN.md` | 349 | **GTM plan** — pricing, launch timeline, metrics |
| `VERTEX_AI_PLAN.md` | 218 | **GCP strategy** — Vertex provider, Marketplace listing |
| `architecture/mindmap.md` | 213 | **System map** — 4-layer architecture + future scale diagram |
| `architecture/the-5-mistakes.md` | 417 | **Competitive analysis** — positioning + blog content |

### `internal/proposals/` — Organized by status

**Done (implemented):**
| File | What it proposed |
|------|-----------------|
| `proposals/done/proposal-code-subtabs.md` | Code tab subtab architecture — built |
| `proposals/done/proposal-chat-panel.md` | Dual-mode chat panel — built |
| `proposals/done/implementation-code-subtabs.md` | Code tab component structure docs — built |

**Pending (not yet implemented):**
| File | What it proposes |
|------|-----------------|
| `proposals/pending/proposal-agent-architecture.md` | LangGraph agent pipeline |
| `proposals/pending/proposal-chat-intent.md` | Chat intent classification + routing |
| `proposals/pending/proposal-help-system.md` | Contextual help / onboarding |
| `proposals/pending/AUTH_PLAN.md` | AuthLib (FastAPI) + Better Auth (Next.js) phases |
| `proposals/pending/sdlc-architecture-plan.md` | Spec-as-source-of-truth ownership model |
| `proposals/pending/BRANDING_LANDING_SPEC.md` | Branding + landing page generation |
| `proposals/pending/GITHUB_INTEGRATION_SPEC.md` | GitHub/GitLab sync (one-way in beta, bidirectional next) |
| `proposals/pending/TEMPLATE_SYSTEM_SPEC.md` | Template marketplace |

### `.agents/` — AI tooling (keep all)
| Path | Purpose |
|------|---------|
| `skills/shadcn-design-system/` | Design system discipline |
| `skills/solid-architecture/` | SOLID patterns |
| `workflows/factory-code-review.md` | Code review workflow |

### `.claude/` — Claude Code config (keep all, fix some)
| File | Purpose |
|------|---------|
| `claude.md` | Project context + rules |
| `agent.md` | Pipeline agent docs |
| `skills.md` | Dev command shortcuts |
| `plans/MASTER_PLAN.md` | Full project plan + phases |
| `plans/*.md` (16 module plans) | Detailed module specs |

---

## 🔧 FIX — ✅ All Resolved

| File | What was fixed |
|------|---------------|
| `.claude/plans/issues-tracking-module.md` | ✅ Full rewrite — markdown-based → DB-backed with Kanban + list view |
| `.claude/plans/capability-modules.md` | ✅ Auth: SuperTokens/Keycloak → AuthLib/Better Auth. Fixed dead `AUTH_PLAN.md` path |
| `docker-compose.yml` | ✅ Extracted `DATABASE_URL`, `CORS_ORIGINS`, `POSTGRES_*` to `.env` variables (12-factor) |
| `internal/LLM_CONFIGURATION.md` | ✅ Verified — models match `.env.example`. Fixed docker-compose default (llama3.2 → llama3.1:8b) |

---

## Post-Cleanup Structure

After cleanup:

```
docs/                                  # User-facing only
├── quickstart.md                      # Setup + first project
└── guide.md                           # How to use each layer

internal/                              # Team reference
├── v0.1.0.md
├── launch-copy.md
├── 12-factor-audit.md
├── LLM_CONFIGURATION.md
├── BLOG_STRATEGY.md
├── GO_TO_MARKET_PLAN.md
├── VERTEX_AI_PLAN.md
├── architecture/
│   ├── mindmap.md
│   ├── the-5-mistakes.md
│   └── initial-research.md
└── proposals/
    ├── done/
    │   ├── proposal-code-subtabs.md
    │   ├── proposal-chat-panel.md
    │   └── implementation-code-subtabs.md
    └── pending/
        ├── proposal-agent-architecture.md
        ├── proposal-chat-intent.md
        ├── proposal-help-system.md
        ├── AUTH_PLAN.md
        ├── sdlc-architecture-plan.md
        ├── BRANDING_LANDING_SPEC.md
        ├── GITHUB_INTEGRATION_SPEC.md
        └── TEMPLATE_SYSTEM_SPEC.md

.claude/
├── claude.md
├── agent.md
├── skills.md
└── plans/
    └── MASTER_PLAN.md + 16 module plans

.agents/
├── skills/shadcn-design-system/SKILL.md
├── skills/solid-architecture/SKILL.md
└── workflows/factory-code-review.md

root/
├── README.md
└── cleanup.md
```