docs: mirror wiki/ folder to GitHub Wiki via CI

[hanwencheng]

Problem

GitHub Wiki and the main repo are two separate git repositories — litentry/agentKeys and litentry/agentKeys.wiki.git. They are not synced. Right now, anything we publish to the wiki has to be edited via the GitHub web UI (or pushed manually from a local clone of the wiki repo), which means:

1. Wiki content skips PR review. Anyone with push access can change a wiki page without code review, without a diff in the main repo, and without any link back to the commit that motivated the change.
2. No audit trail. Wiki history lives in a separate repo most contributors never look at. There is no way to ask "what wiki updates landed alongside this feature?"
3. Drift. Wiki pages and source-tree docs (e.g. docs/manual-test-stage4.md, the planned docs/field-name-translation.md from docs: human-readable keychain metadata in manual tests + field-name translation design note #1) drift out of sync because they live in different repos with different review surfaces.

We need wiki content to be authored and reviewed inside the main repo, then mirrored automatically to the wiki repo.

Solution

Add a wiki/ folder to the main repo as the canonical source for all GitHub Wiki content, and a one-way GitHub Action that mirrors it to litentry/agentKeys.wiki.git on every push to main that touches wiki/.

This gives us:

• Wiki edits go through PRs like any other code change.
• Wiki history is part of main repo history.
• The wiki repo is purely derived — you can blow it away and republish from main at any time.
• Contributors never need a separate clone of the wiki repo.

Implementation

Step 1 — Initialize the wiki repo (one-time, manual).
GitHub does not create litentry/agentKeys.wiki.git until at least one wiki page has been saved through the web UI. Visit https://github.com/litentry/agentKeys/wiki, click "Create the first page", save anything (even just # Welcome). This is a prerequisite for the workflow to work.

Step 2 — Add wiki/ folder to the main repo.
Move/seed wiki content under wiki/ in the main repo. Initial content suggestion (from existing docs):

wiki/
├── Home.md                    # landing page; index of other pages
├── Architecture.md            # mirror or summary of docs/spec/architecture.md
├── Manual-Testing.md          # mirror or summary of docs/manual-test-stage4.md
├── Field-Name-Translation.md  # mirror of docs/field-name-translation.md (when #1 lands)
└── Development-Stages.md      # mirror or summary of docs/spec/plans/development-stages.md

The actual seeding can be done in a separate PR; this issue tracks the mirror infrastructure.

Step 3 — Add the workflow.
Create .github/workflows/publish-wiki.yml:

name: Publish wiki
on:
  push:
    branches: [main]
    paths: ['wiki/**']

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Andrew-Chen-Wang/github-wiki-action@v4
        with:
          path: wiki/
          # token defaults to GITHUB_TOKEN, which has wiki write access

That is the whole workflow. On every push to main that touches wiki/, the action clones agentKeys.wiki.git, copies wiki/* over, commits, and pushes.

Step 4 — Lock down direct wiki edits (optional but recommended).
In repo settings → Features → Wikis, set "Restrict editing to collaborators only". This prevents random outside contributors from editing the wiki through the web UI and getting clobbered on the next mirror push. Even better: document in wiki/Home.md itself: "This wiki is generated from wiki/ in the main repo. Edit there, not here."

Tradeoffs / out of scope

• One-way mirror only. If someone edits the wiki through the web UI after the workflow runs, those edits will be overwritten on the next push to main that touches wiki/. This is the intended behavior — main repo is the source of truth. Document this clearly on the wiki home page.
• No two-way sync. We are not building a system that lets people edit the wiki in the browser and have those edits land back in the main repo. That would require a separate workflow (wiki webhook → main repo PR), which is significantly more complex and not worth the effort for our scale.
• No automatic conversion from docs/. The mirror copies wiki/* verbatim. If we want certain docs/ files to also appear on the wiki, we either (a) duplicate them under wiki/ and accept the manual sync cost, or (b) add a build step that copies/transforms docs/foo.md → wiki/Foo.md before the mirror runs. Option (a) is fine for v0; option (b) can be a follow-up if the duplication becomes painful.
• Not changing any source code. This is 100% docs + CI configuration.

Verification plan

1. Initialize wiki repo manually via the web UI (one-time prereq above).
2. Land the workflow in a PR. Merge to main.
3. Test with a trivial wiki page. Create wiki/Home.md with # Welcome, commit, push. The Actions tab should show the Publish wiki workflow running. After ~30s, refresh https://github.com/litentry/agentKeys/wiki and confirm the home page renders.
4. Test path filtering. Push a commit that does not touch wiki/ (e.g., a Rust source change). Confirm the workflow does not run.
5. Test internal wiki links. Add a second page wiki/Architecture.md, link to it from wiki/Home.md with [Architecture](Architecture). After mirror, confirm the link works on the published wiki.
6. Test deletion. Remove a wiki page in main repo, push. Confirm it disappears from the published wiki on the next run.

Files touched

Path	Change
.github/workflows/publish-wiki.yml	New file — the mirror workflow above
wiki/Home.md	New file — initial landing page (can be a separate PR)
wiki/ (other pages)	New files — content seeding in follow-up PRs

Related

• docs: human-readable keychain metadata in manual tests + field-name translation design note #1 (the field-name-translation design note will be a good first wiki page once the mirror is set up — it cross-references multiple files and would benefit from being browsable on the wiki rather than only on GitHub blob URLs).

---

Filed from a planning conversation. Happy to implement once approved, or hand off.