# 森林AI Documentation And Verification Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 统一开发配置、演示数据、README 和最终验证，使新开发者能够按文档启动森林AI并复现验收结果。

**Architecture:** Docker Compose、YAML 配置和 README 使用同一组开发默认值；本地数据通过显式 seed 命令创建。最终验证脚本只读取环境配置，不携带真实凭据。

**Tech Stack:** Docker Compose、PostgreSQL 16、Go、Node.js、Vite、Tauri。

## Global Constraints

- 不提交真实凭据、本地数据库、文件存储、日志、审计截图或构建产物。
- 开发配置可以包含明确标注的非生产默认值。
- 程序启动不得自动 drop 表或清空生产数据。
- README 必须为 UTF-8 中文，名称统一为“森林AI”。

---

### Task 1: 开发配置与演示数据一致性

**Files:**
- Modify: `infra/docker-compose.yml`
- Modify: `backend/etc/agent.dev.yaml`
- Modify: `backend/internal/config/config.go`
- Modify: `backend/internal/config/config_test.go`
- Modify: `backend/internal/seed/demo.go`
- Modify: `backend/internal/seed/demo_test.go`
- Modify: `.gitignore`

**Interfaces:**
- Produces: one PostgreSQL DSN shared by Compose and development YAML; explicit `go run ./cmd/seed` reset-safe seed workflow.

- [ ] **Step 1: Write failing configuration tests**

Assert the loaded development config uses port 9150, `/api/v1` compatible CORS origins, a non-empty storage dir, and that seed is idempotent while preserving project-scoped tags.

- [ ] **Step 2: Verify failures**

Run: `go test ./internal/config ./internal/seed -v`

Expected: FAIL where config lacks allowed origins or seed contracts.

- [ ] **Step 3: Align Compose and YAML**

Use the same development values in both files: user `agent`, password `agent`, database `agent`, host `localhost`, port `5432`. Keep secrets explicitly marked as development-only. Add `.superpowers/`, `backend/tmp/`, `backend/data/`, `apps/web_v1/test-results/` and build outputs to `.gitignore`.

- [ ] **Step 4: Verify config and seed**

Run: `go test ./internal/config ./internal/seed -v`

Expected: PASS.

- [ ] **Step 5: Commit**

```powershell
git add infra/docker-compose.yml backend/etc/agent.dev.yaml backend/internal/config backend/internal/seed .gitignore
git commit -m "chore: align forest AI development setup"
```

### Task 2: 重写 README

**Files:**
- Modify: `README.md`
- Modify: `docs/mvp-verification.md`

**Interfaces:**
- Produces: authoritative local setup and verification guide.

- [ ] **Step 1: Check every documented command before writing**

Run the exact commands that README will contain: Compose startup, backend API startup, seed, Web dev server, backend tests, visual check, build and lint. Record only commands that actually succeed.

- [ ] **Step 2: Replace README with the approved structure**

Use these exact top-level sections: `产品定位`, `MVP 范围`, `技术栈`, `目录结构`, `快速开始`, `配置`, `API v1 概览`, `验证`, `桌面端`, `常见问题`, `安全说明`.

Document `POST /api/v1/auth/login`, project/workspace, task/tag/source/cron, Inbox, search and AI session endpoints without embedding tokens or real secrets.

- [ ] **Step 3: Update verification documentation**

Include the current expected commands and artifact paths; remove stale Svelte references, old API paths, old product names and deprecated ports.

- [ ] **Step 4: Verify text consistency**

Run:

```powershell
rg -n "SenlinAI Agent Workbench|森林Agent|/api/projects|apps/web/|Svelte" README.md docs/mvp-verification.md
```

Expected: no matches.

- [ ] **Step 5: Commit**

```powershell
git add README.md docs/mvp-verification.md
git commit -m "docs: update forest AI setup and verification"
```

### Task 3: 全量验证与前后截图对比

**Files:**
- Modify: `apps/web_v1/scripts/visual-check.mjs`
- Create: `docs/forest-ai-audit.md`

**Interfaces:**
- Produces: repeatable desktop/mobile audit summary with final screenshots.

- [ ] **Step 1: Run backend verification**

Run: `go test ./...`

Expected: PASS for every package.

- [ ] **Step 2: Run frontend verification**

Run: `node scripts/structure-check.mjs; $env:VISUAL_CHECK_PORT='4174'; node scripts/visual-check.mjs; npm run build; npm run lint`

Expected: PASS; build may report a size warning but no error.

- [ ] **Step 3: Run PostgreSQL integration checks when DATABASE_URL is present**

Run: `go test ./internal/models -run TestPostgresPing -v`

Expected: PASS when `DATABASE_URL` is configured; otherwise the test reports its documented skip.

- [ ] **Step 4: Capture final evidence**

Capture and inspect 1440×1024 login, workspace, project overview and tasks, plus 390×844 login and project navigation. Compare against the five accepted audit screenshots from the design phase and document visible fixes and remaining limits in `docs/forest-ai-audit.md`.

- [ ] **Step 5: Verify repository cleanliness**

Run: `git status --short`

Expected: only intended source/docs changes are present; no logs, test screenshots, database files or secrets.

- [ ] **Step 6: Commit**

```powershell
git add apps/web_v1/scripts/visual-check.mjs docs/forest-ai-audit.md
git commit -m "test: verify forest AI MVP unification"
```