# Wiki as Git Repository

Gitea wikis are backed by bare git repos at `<repo-url>.wiki.git`. Instead of using the API (base64 encoding, one page at a time), we clone the wiki repo as a project subfolder and work with plain markdown files.

## Wiki directory

The wiki is cloned into `.wiki/` at the project root:

```
project-root/
├── .claude/.env
├── .wiki/           ← wiki git repo
│   ├── Home.md
│   ├── feature-12-user-auth.md
│   ├── feature-12-user-auth-t01.md
│   └── ...
└── src/
```

## Setup (once per project)

```bash
set -a; source .claude/.env; set +a

WIKI_URL="https://${GITEA_USER}:${GITEA_ACCESS_TOKEN}@${GITEA_HOST#https://}/${owner}/${repo}.wiki.git"

if [ -d .wiki/.git ]; then
  git -C .wiki pull --rebase
else
  git clone "$WIKI_URL" .wiki
fi
```

If the wiki repo doesn't exist yet (first wiki page), initialize it:

```bash
mkdir -p .wiki && cd .wiki
git init
git remote add origin "$WIKI_URL"
echo "# Wiki" > Home.md
git add Home.md
git commit -m "init wiki"
git push -u origin main
```

## Writing pages

Just write markdown files in `.wiki/`:

```bash
# Write a page (filename = page name on Gitea)
cat > .wiki/feature-12-user-auth.md << 'EOF'
# User Authentication
...
EOF
```

Page naming rules:
- Filename (without `.md`) = wiki page name
- Use kebab-case: `feature-12-user-auth.md`
- Sub-tasks: `feature-12-user-auth-t01.md`
- Home/index: `Home.md`

## Publishing

After writing all pages, commit and push in one go:

```bash
cd .wiki
git add -A
git commit -m "feat(wiki): publish plan for issue #12"
git push
```

This is atomic — all pages appear at once, unlike the API approach.

## Reading pages

Just read files from `.wiki/`:

```bash
cat .wiki/feature-12-user-auth.md
```

## Wiki URL construction

Page URLs on Gitea: `https://$GITEA_HOST/$owner/$repo/wiki/$page-name`

Where `$page-name` is the filename without `.md`.

## .gitignore

Add `.wiki/` to the project's `.gitignore` — it's a separate repo, not part of the main project:

```
.wiki/
```

## Advantages over API

- No base64 encoding
- Write multiple pages, publish atomically
- Read/edit pages with standard file tools (Read, Edit, Write)
- Full git history for wiki changes
- Works offline, push when ready