Switch docs-generate.yml to git-based distribution, unblocking OpenWiki

.github/workflows/docs-generate.yml

@@ -8,6 +8,13 @@ name: Generate Docs (reusable)
 # Requires the calling workflow to pass `secrets: inherit` (or explicitly
 # forward OPENROUTER_API_KEY) so the shared org-wide OpenRouter key reaches
 # this job.
+#
+# @crewcircle/docs-gen is NOT published to npm (blocked on an npm org/token
+# permissions issue — see packages/docs-gen/README.md). Until that's sorted,
+# this checks out crewcircle-website directly and builds the package from
+# source rather than `npx`-installing it from the registry. OpenWiki itself
+# is unaffected — it's a normal published third-party package, still
+# installed via `npx` as usual.
 
 on:
   workflow_call:
@@ -31,24 +38,42 @@ jobs:
       contents: write
       pull-requests: write
     steps:
-      - name: Checkout
+      - name: Checkout target repo
         uses: actions/checkout@v4
         with:
+          path: target
           persist-credentials: true
 
+      - name: Checkout docs-gen source (crewcircle-website)
+        uses: actions/checkout@v4
+        with:
+          repository: crewcircle/crewcircle-website
+          path: docs-gen-src
+          sparse-checkout: |
+            packages/docs-gen
+          sparse-checkout-cone-mode: false
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: "20"
+          node-version: "22"
+
+      - name: Build docs-gen
+        working-directory: docs-gen-src/packages/docs-gen
+        run: |
+          npm install
+          npm run build
 
-      - name: Run OpenWiki via @crewcircle/docs-gen
-        run: npx --yes @crewcircle/docs-gen generate --mode=${{ inputs.mode }}
+      - name: Run OpenWiki via docs-gen
+        working-directory: target
+        run: node ../docs-gen-src/packages/docs-gen/dist/cli.js generate --mode=${{ inputs.mode }}
         env:
           OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
 
       - name: Create documentation update pull request
         uses: peter-evans/create-pull-request@v7
         with:
+          path: target
           add-paths: |
             openwiki
             AGENTS.md
@@ -57,4 +82,4 @@ jobs:
           commit-message: "docs: update generated documentation"
           title: "docs: update generated documentation"
           body: |
-            Automated documentation update via `@crewcircle/docs-gen` (OpenWiki, mode: ${{ inputs.mode }}).
+            Automated documentation update via `@crewcircle/docs-gen` (OpenWiki, mode: ${{ inputs.mode }}), built from source (git-based distribution — see workflow comments).

packages/docs-gen/README.md

@@ -6,8 +6,23 @@ every repo runs the same CLI instead of a copy-pasted CI script.
 
 ## Usage
 
+**Not published to npm** — `@crewcircle`'s npm organization has an
+unresolved token/permissions issue (org exists, publish still 404s; see
+git history on this file / `.github/workflows/release.yml` for the
+investigation). Don't `npx @crewcircle/docs-gen` yet, it will fail to
+resolve. CrewCircle repos consume this package by building it from source
+instead — see `.github/workflows/docs-generate.yml`, which checks out
+`crewcircle-website`, runs `npm install && npm run build` inside
+`packages/docs-gen`, and invokes `dist/cli.js` directly with `node`. Once
+npm publishing is fixed, this can switch back to a plain `npx` install with
+no change to the CLI itself.
+
+For manual/local use against a real target repo:
+
 ```sh
-npx @crewcircle/docs-gen generate --mode=engineering
+cd packages/docs-gen && npm install && npm run build
+cd /path/to/target-repo
+node /path/to/crewcircle-website/packages/docs-gen/dist/cli.js generate --mode=engineering
 ```
 
 - Writes `openwiki/INSTRUCTIONS.md` from the matching template in
@@ -22,15 +37,29 @@ CrewCircle GitHub org secret).
 
 ## Model choice
 
-Defaults to `inclusionai/ling-2.6-flash` via OpenRouter — the cheapest model
-on OpenRouter's live catalog, at the time this was written, that both supports
-tool-calling (required — OpenWiki is an agentic CLI that reads files via tool
-calls) and has enough context (262k tokens) to read real source files. Free-tier
-(`:free`) models were intentionally not chosen as the default: they share a
-global rate-limited pool (as low as 20 requests/day) too fragile for a CI job
-that needs many tool-call round-trips per run. Override per-repo by setting
-`OPENWIKI_MODEL_ID` in the calling workflow's environment before invoking this
-CLI — it wins over the default.
+Defaults to `qwen/qwen3-30b-a3b-instruct-2507` via OpenRouter. Two cheaper
+options were tried and ruled out by real CI runs, not just price research:
+
+1. `inclusionai/ling-2.6-flash` (literal cheapest tool-calling model on
+   OpenRouter at the time) — hit a persistent `429` from its backing
+   provider (Novita's shared, non-BYOK pool), twice in a row, not transient.
+2. `mistralai/mistral-nemo` — no rate-limit issue, but too weak to follow
+   OpenWiki's own init-vs-update reasoning: it looked at recent git log,
+   saw unrelated commits, and concluded "wiki already current" without ever
+   generating anything, despite `openwiki/` not existing yet in the repo.
+
+`qwen3-30b-a3b-instruct-2507` (30B MoE, ~3.3B active params, 262k context,
+tool-calling supported) correctly did a full first-pass generation end to
+end — verified via a real run producing accurate, substantive pages (see
+PR history on this repo). Costs more than the first two
+($0.048/$0.193 per M tokens) but is still cheap in absolute terms, and
+correctness matters more than shaving fractions of a cent on a job that
+runs occasionally. Free-tier (`:free`) models were intentionally not
+chosen as the default either: they share a global rate-limited pool (as
+low as 20 requests/day) too fragile for a CI job that needs many
+tool-call round-trips per run. Override per-repo by setting
+`OPENWIKI_MODEL_ID` in the calling workflow's environment before invoking
+this CLI — it wins over the default.
 
 ## Modes
 

packages/docs-gen/src/defaults.ts

@@ -5,7 +5,7 @@
  */
 export const DEFAULT_ENV: Record<string, string> = {
   OPENWIKI_PROVIDER: "openrouter",
-  OPENWIKI_MODEL_ID: "inclusionai/ling-2.6-flash",
+  OPENWIKI_MODEL_ID: "qwen/qwen3-30b-a3b-instruct-2507",
   OPENWIKI_TELEMETRY_DISABLED: "1",
 };