# S02 Research: Forgejo Knowledgebase Bootstrap

## Summary

This slice populates a Forgejo wiki with comprehensive Chrysopedia architecture documentation. The Forgejo instance is live at `https://git.xpltd.co` (container `forgejo-8099` on ub01, port 8099→3000). No `chrysopedia` repo exists yet — it must be created first, then its wiki populated with markdown pages derived from the site audit report (S01 output), PROJECT.md, DECISIONS.md, KNOWLEDGE.md, and source code structure.

**Depth calibration: Targeted.** Forgejo's wiki is just a git repo of markdown files with a simple API. The content already exists in the codebase and S01 audit report. The only unknowns were the API shape (now resolved) and authentication (needs a token from the user).

## Recommendation

**Approach: Git-push bulk wiki content** (not individual API calls).

1. Create the `xpltdco/chrysopedia` repo via Forgejo API
2. Clone the wiki git repo (`chrysopedia.wiki.git`)
3. Write all markdown pages locally + `_Sidebar.md` navigation
4. Git push in one commit

This is simpler and more reliable than calling `POST /repos/{owner}/{repo}/wiki/new` per page (which requires base64-encoding each page body). The git approach also allows `_Sidebar.md` and `_Footer.md` custom navigation, which the API doesn't expose.

## Implementation Landscape

### Forgejo Instance Details

- **URL:** `https://git.xpltd.co` (ROOT_URL in app.ini)
- **Container:** `forgejo-8099` on ub01, maps `0.0.0.0:8099→3000/tcp` and `0.0.0.0:2222→22/tcp`
- **Version:** Forgejo 10.0.3 (Gitea 1.22.0 compatible)
- **DB:** `forgejo-db` (PostgreSQL, separate from Chrysopedia's)
- **Runner:** `forgejo-runner` (CI runner, not relevant to wiki)
- **Organization:** `xpltdco` (existing, owns 4 repos: ci-test, fractafrag, media-rip, tubearr)
- **DNS:** `git.xpltd.co` and `forgejo.xpltd.co` both resolve to `10.0.0.9` (nginx01) via AdGuard rewrites. SSL cert exists for `git.xpltd.co`. The roadmap references `forgejo.xpltd.co` but the canonical domain per `app.ini` is `git.xpltd.co`.

### API Surface (Wiki-Related)

All wiki endpoints are under `/api/v1/repos/{owner}/{repo}/wiki/`:

| Method | Path | Notes |
|--------|------|-------|
| `POST` | `/wiki/new` | Body: `{title, content_base64, message}` |
| `GET` | `/wiki/pages` | List all pages |
| `GET` | `/wiki/page/{pageName}` | Get single page |
| `PATCH` | `/wiki/page/{pageName}` | Edit page: `{title, content_base64, message}` |
| `DELETE` | `/wiki/page/{pageName}` | Delete page |
| `GET` | `/wiki/revisions/{pageName}` | Page history |

Auth: `Authorization: token <api_token>` header. Token created via Forgejo UI (Settings → Applications → Generate New Token) with `write:repository` scope.

### Repo Creation API

`POST /api/v1/orgs/{org}/repos` with body: `{name, description, auto_init, default_branch, private}`. Creates repo under the `xpltdco` org.

### Wiki as Git Repo

Per Forgejo docs, the wiki is a separate git repo at `<repo>.wiki.git`. It consists of markdown files rendered automatically. Special files:
- `Home.md` — default landing page
- `_Sidebar.md` — navigation sidebar on every page
- `_Footer.md` — footer on every page

Pages are linked by filename (without `.md`): `[[Page Name]]` or `[text](Page-Name)`.

### Authentication Requirement

**A Forgejo API token is needed.** No token exists in environment variables or config files on ub01. The executor will need to:
1. Either receive a pre-created token via `secure_env_collect`, OR
2. Create one via the Forgejo API using basic auth: `POST /api/v1/users/{username}/tokens` with BasicAuth credentials

The token needs `write:repository` and `write:wiki` scopes (or broad `write` scope).

### Content Sources → Wiki Pages

| Wiki Page | Source(s) | Description |
|-----------|-----------|-------------|
| `Home.md` | PROJECT.md | Project overview, what's built, current state |
| `Architecture.md` | Site Audit Report §Executive Summary, §Infrastructure Stack | System architecture, Docker services, network topology |
| `Data-Model.md` | Site Audit Report §Data Model, `backend/models.py` | All 13+ SQLAlchemy models, relationships, enums |
| `API-Surface.md` | Site Audit Report §API Surface Map | All 41 endpoints grouped by domain |
| `Frontend.md` | Site Audit Report §Route Map, §Component Inventory, §CSS Architecture | Routes, components, hooks, CSS custom properties |
| `Pipeline.md` | PROJECT.md pipeline section, KNOWLEDGE.md pipeline entries | 6-stage LLM pipeline, prompt system, debug mode |
| `Deployment.md` | Site Audit Report §Infrastructure Stack, docker-compose.yml | Docker Compose setup, bind mounts, rebuild commands |
| `Development-Guide.md` | CLAUDE.md quick commands, KNOWLEDGE.md patterns | Local dev setup, common gotchas, testing |
| `Decisions.md` | DECISIONS.md | Architectural decisions register (D001-D035) |
| `_Sidebar.md` | (generated) | Navigation links to all pages |

### Execution Constraints

- **SSH access to ub01** is available from the working machine for git operations
- **Git clone** of the wiki repo requires the wiki to have at least one page (or use the API to create the first page, which initializes the wiki git repo)
- **Alternative:** Use the API for all pages — avoids the git-clone bootstrap chicken-and-egg, but requires base64 encoding and doesn't support `_Sidebar.md` via API
- **Hybrid approach (recommended):** Create `Home.md` via API (initializes wiki repo), then git clone, add remaining pages + `_Sidebar.md`, push

### Risks

1. **Token availability** — Need user to create/provide a Forgejo API token. Without it, nothing can be automated. **Mitigation:** `secure_env_collect` for the token, or create via BasicAuth API if username/password available.
2. **Wiki git clone URL** — The SSH clone URL is `ssh://git@git.xpltd.co:2222/xpltdco/chrysopedia.wiki.git`. Need SSH key access or HTTPS clone with token auth: `https://{user}:{token}@git.xpltd.co/xpltdco/chrysopedia.wiki.git`.
3. **Domain mismatch** — Roadmap says `forgejo.xpltd.co` but canonical is `git.xpltd.co`. Use `git.xpltd.co` everywhere.

## Natural Seams

This is a 2-task slice:

**Task 1: Create repo + bootstrap wiki infrastructure**
- Collect Forgejo API token
- Create `xpltdco/chrysopedia` repo via API
- Create initial `Home.md` via wiki API (initializes wiki git repo)
- Verify repo and wiki are accessible at `https://git.xpltd.co/xpltdco/chrysopedia/wiki/`

**Task 2: Populate all wiki pages**
- Git clone the wiki repo via HTTPS with token auth
- Generate all 8-9 wiki pages from existing content sources
- Add `_Sidebar.md` navigation
- Git commit + push
- Verify all pages render at `https://git.xpltd.co/xpltdco/chrysopedia/wiki/`

Task 1 is the risky bit (auth, API correctness). Task 2 is straightforward content transformation.
