@chronova/wiki-agent 1.1.4 → 1.2.1

package/README.md

@@ -109,85 +109,21 @@ Environment variables take priority over config files.
 
 ## GitHub Actions
 
-Running `wiki --init` automatically creates `.github/workflows/update-wiki.yml` in your repo. The workflow:
+Running `wiki --init` automatically creates `.github/workflows/update-wiki.yml` in your repo. The workflow publishes generated pages to your repository's **GitHub Wiki tab**, not to the main repo's file tree:
 
 1. Generates a GitHub App token if `APP_CLIENT_ID` and `APP_PRIVATE_KEY` secrets are set (falls back to `GITHUB_TOKEN`)
-2. Checks out your repo
-3. Clones and builds wiki-agent from `nx-solutions-ug/wiki-agent`
-4. Runs `wiki --update --print` with your Ollama Cloud credentials
-5. Reads `.wiki/.last-update-report.md` and uses it as the PR body
-6. Creates a pull request with the `.wiki/` changes
-
-```yaml
-name: Wiki Update
-on:
-  workflow_dispatch:
-  push:
-    branches:
-      - main
-  schedule:
-    - cron: "0 8 * * *"
-permissions:
-  contents: write
-  pull-requests: write
-jobs:
-  update:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Generate token
-        id: token
-        uses: actions/create-github-app-token@v3
-        with:
-          client-id: ${{ secrets.APP_CLIENT_ID }}
-          private-key: ${{ secrets.APP_PRIVATE_KEY }}
-        continue-on-error: true
-
-      - uses: actions/checkout@v7
-        with:
-          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}
-
-      - uses: actions/setup-node@v7
-        with:
-          node-version: "25"
-
-      - name: Build Wiki Agent
-        run: |
-          git clone --branch main --depth 1 https://github.com/nx-solutions-ug/wiki-agent.git /tmp/wiki-agent
-          cd /tmp/wiki-agent
-          npm install
-          npx tsc -p tsconfig.json
-
-      - name: Run Wiki Agent
-        run: node /tmp/wiki-agent/dist/cli.js --update --print
-        env:
-          WIKI_OLLAMA_MODE: cloud
-          WIKI_OLLAMA_API_KEY: ${{ secrets.WIKI_OLLAMA_API_KEY }}
-          WIKI_MODEL: ${{ vars.WIKI_MODEL || 'kimi-k2.7-code' }}
-
-      - name: Generate timestamp
-        id: timestamp
-        run: echo "timestamp=$(date +%s)" >> $GITHUB_OUTPUT
-
-      - name: Read update report
-        id: report
-        run: |
-          if [ -f .wiki/.last-update-report.md ]; then
-            echo "body<<EOF" >> $GITHUB_OUTPUT
-            cat .wiki/.last-update-report.md >> $GITHUB_OUTPUT
-            echo "EOF" >> $GITHUB_OUTPUT
-          else
-            echo "body=Automated wiki documentation update." >> $GITHUB_OUTPUT
-          fi
-
-      - uses: peter-evans/create-pull-request@v8
-        with:
-          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}
-          add-paths: .wiki
-          branch: wiki/update-${{ steps.timestamp.outputs.timestamp }}
-          commit-message: "docs: update wiki"
-          title: "docs: update wiki"
-          body: ${{ steps.report.outputs.body }}
-```
+2. Checks out your repo, clones and builds wiki-agent from `nx-solutions-ug/wiki-agent`
+3. Runs `wiki --update --print` with your Ollama Cloud credentials, staging pages under `.wiki/`
+4. Probes the wiki remote (`<repo>.wiki.git`) with `git ls-remote` to detect whether the wiki has been initialized
+5. If there are content changes and the wiki is initialized: clones `<repo>.wiki.git`, syncs the `.wiki/` content (excluding `config.json`, `.last-update-report.md`, `.last-updated.json`) via `rsync`, commits on a `wiki/update-<timestamp>` branch, and pushes
+6. Opens a pull request against the wiki repo (`--repo <owner>/<repo>.wiki`, base `master`) with `.wiki/.last-update-report.md` as the body — a human merges to make updates live
+7. Always opens a `docs: wiki staging snapshot` pull request against the main repo with the `.wiki/` changes, so the staged content stays auditable
+
+### Bootstrap the wiki first
+
+GitHub wikis must be initialized once through the UI before they can be pushed to programmatically. Open the **Wiki** tab in your repository, create the first page (any content), then run the workflow. Until then the publish step is skipped with a warning; the staging PR still opens so you can inspect the generated content.
+
+The full workflow is written to `.github/workflows/update-wiki.yml` by `wiki --init`. See that file (or the template in [`src/agent.ts`](src/agent.ts) `createWorkflowFile`) for the authoritative, current definition. The steps in brief: generate token → checkout → build wiki-agent → run `--update --print` → probe wiki remote → if there are content changes and the wiki is initialized, clone `<repo>.wiki.git`, `rsync` the staged `.wiki/` content (excluding `config.json` and the run metadata), commit on `wiki/update-<timestamp>`, push → open a PR against the wiki repo (base `master`) → open a `docs: wiki staging snapshot` PR against the main repo.
 
 ### Required secrets
 
@@ -196,6 +132,7 @@ jobs:
 | `WIKI_OLLAMA_API_KEY` | Yes | Ollama Cloud API key |
 | `APP_CLIENT_ID` | No | GitHub App client ID for token generation (falls back to `GITHUB_TOKEN`) |
 | `APP_PRIVATE_KEY` | No | GitHub App private key |
+| `WIKI_PUSH_TOKEN` | No | PAT with `repo` scope used to push to the wiki repo. If unset, the GitHub App token or `GITHUB_TOKEN` is used. Set this only if the default token cannot push to the wiki repo. |
 
 ### Optional variables
 

package/dist/agent.js

@@ -226,10 +226,28 @@ async function createWorkflowFile(projectRoot) {
         "          WIKI_OLLAMA_MODE: cloud",
         '          WIKI_OLLAMA_API_KEY: ${{ secrets.WIKI_OLLAMA_API_KEY }}',
         "          WIKI_MODEL: ${{ vars.WIKI_MODEL || 'kimi-k2.7-code' }}",
+        "",
         "      - name: Generate timestamp",
         "        id: timestamp",
         "        run: echo \"timestamp=$(date +%s)\" >> $GITHUB_OUTPUT",
         "",
+        "      - name: Repository coordinates",
+        "        id: coords",
+        "        run: echo \"owner_repo=${GITHUB_REPOSITORY}\" >> $GITHUB_OUTPUT",
+        "",
+        "      - name: Detect wiki initialization",
+        "        id: wiki-init",
+        "        env:",
+        "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "        run: |",
+        "          REMOTE=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"",
+        "          if git ls-remote --exit-code \"$REMOTE\" HEAD >/dev/null 2>&1; then",
+        "            echo \"initialized=true\" >> $GITHUB_OUTPUT",
+        "          else",
+        "            echo \"initialized=false\" >> $GITHUB_OUTPUT",
+        "            echo \"::warning::Wiki is not initialized. Create the first page in the GitHub UI (Wiki tab -> New Page), then rerun. Staging PR will still be opened.\" >> $GITHUB_OUTPUT",
+        "          fi",
+        "",
         "      - name: Check for changes",
         "        id: report",
         "        run: |",
@@ -246,14 +264,56 @@ async function createWorkflowFile(projectRoot) {
         "            echo \"has_changes=false\" >> $GITHUB_OUTPUT",
         "          fi",
         "",
-        "      - name: Create Wiki update pull request",
+        "      - name: Publish to wiki repo",
+        "        id: publish",
+        "        if: steps.report.outputs.has_changes == 'true' && steps.wiki-init.outputs.initialized == 'true'",
+        "        env:",
+        "          TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "        run: |",
+        "          BRANCH=\"wiki/update-${{ steps.timestamp.outputs.timestamp }}\"",
+        "          WIKI_URL=\"https://x-access-token:${TOKEN}@github.com/${{ steps.coords.outputs.owner_repo }}.wiki.git\"",
+        "          rm -rf /tmp/wiki",
+        "          git clone \"$WIKI_URL\" /tmp/wiki",
+        "          cd /tmp/wiki",
+        "          git checkout -b \"$BRANCH\"",
+        "          rsync -a --delete \\",
+        "            --exclude='.last-update-report.md' \\",
+        "            --exclude='.last-updated.json' \\",
+        "            --exclude='config.json' \\",
+        "            \"$GITHUB_WORKSPACE/.wiki/\" ./",
+        "          git add -A",
+        "          if ! git diff --cached --quiet; then",
+        "            git -c user.name='wiki-agent[bot]' -c user.email='bot@wiki-agent' \\",
+        "              commit -m \"docs: update wiki\"",
+        "            if ! git push origin \"$BRANCH\" 2>&1 | tee /tmp/wiki-push.log; then",
+        "              echo \"::error::Failed to push to the wiki repo. Ensure the GitHub App has contents:write on the repository (which covers the wiki), or set a WIKI_PUSH_TOKEN secret with repo scope.\"",
+        "              exit 1",
+        "            fi",
+        "            echo \"branch=$BRANCH\" >> $GITHUB_OUTPUT",
+        "          else",
+        "            echo \"::warning::No net wiki content changes after sync; skipping wiki push.\"",
+        "            echo \"branch=\" >> $GITHUB_OUTPUT",
+        "          fi",
+        "",
+        "      - name: Open wiki update pull request",
+        "        if: steps.report.outputs.has_changes == 'true' && steps.wiki-init.outputs.initialized == 'true' && steps.publish.outputs.branch != ''",
+        "        env:",
+        "          GH_TOKEN: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "        run: |",
+        "          gh pr create --repo \"${{ steps.coords.outputs.owner_repo }}.wiki\" \\",
+        "            --head \"wiki/update-${{ steps.timestamp.outputs.timestamp }}\" \\",
+        "            --base master \\",
+        "            --title \"docs: update wiki\" \\",
+        "            --body-file .wiki/.last-update-report.md",
+        "",
+        "      - name: Create wiki staging snapshot pull request",
         "        uses: peter-evans/create-pull-request@v8",
         "        if: steps.report.outputs.has_changes == 'true'",
         "        with:",
-        "          token: ${{ steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
-        "          branch: wiki/update-${{ steps.timestamp.outputs.timestamp }}",
+        "          token: ${{ secrets.WIKI_PUSH_TOKEN || steps.token.outputs.token || secrets.GITHUB_TOKEN }}",
+        "          branch: wiki/staging-${{ steps.timestamp.outputs.timestamp }}",
         "          add-paths: .wiki",
-        '          title: "docs: update wiki"',
+        '          title: "docs: wiki staging snapshot"',
         '          body: ${{ steps.report.outputs.body }}',
     ].join("\n");
     await writeFile(workflowPath, workflow, "utf8");

package/dist/prompt.js

@@ -39,6 +39,7 @@ You cannot run build tools, package managers, test runners, scripts, or any prog
 
 # Output location
 - Write documentation under .wiki/ in the project root. Use paths such as .wiki/quickstart.md, .wiki/architecture/overview.md, .wiki/cli/usage.md.
+- Your output is published to the repository's GitHub Wiki tab after the run. Wiki page titles come from filenames, so never use the characters \ / : * ? " < > | in wiki file names.
 - Never write markdown files outside .wiki/.
 - Each wiki page must start with YAML frontmatter:
   ---
@@ -95,7 +96,7 @@ ${gitSummary ?? "(not available)"}
 `.trim();
     }
     return `
-Update the existing OpenWiki documentation for this repository.
+Update the existing wiki documentation for this repository.
 
 Inspect .wiki/, identify recent source changes or newly relevant evidence, and refresh only the documentation pages directly affected by those changes. Use the git evidence below when available. Keep edits surgical: do not rewrite accurate sections, do not update source maps or git evidence just to refresh them, and do not make formatting-only changes. If the wiki is already current, do not edit files.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronova/wiki-agent",
-  "version": "1.1.4",
+  "version": "1.2.1",
   "description": "Standalone Ollama-only documentation agent",
   "type": "module",
   "bin": {