From bcc51b4eb2de3e113e5af6702301faf2eabb25cd Mon Sep 17 00:00:00 2001 From: CrewCircle Date: Wed, 29 Jul 2026 15:21:32 +1000 Subject: [PATCH 1/4] Switch docs-generate.yml to git-based distribution, unblocking OpenWiki MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit @crewcircle/docs-gen still isn't publishable to npm — the org exists but publishes 404 with a permission-flavored error even after fixing the npm CLI version bug (confirmed via a real retry: same class of error, worse diagnostics). Rather than keep blocking OpenWiki generation on an unresolved npm/token issue, this checks out crewcircle-website directly in the reusable workflow, builds packages/docs-gen from source (npm install && npm run build, standalone — verified it doesn't need the monorepo root/workspace context), and invokes dist/cli.js with node instead of `npx @crewcircle/docs-gen`. openwiki itself is unaffected by any of this — it's a normal published third-party package and continues to be npx-installed from the real registry, same as before. No changes needed to the CLI itself: it already resolves its own template files via import.meta.url (relative to the script) rather than process.cwd() (the invocation directory), so running it via a separate checkout+build works the same as running it via npx would have. Verified locally end-to-end (build standalone in an isolated copy, run the CLI from a separate directory): openwiki installs correctly via npx, INSTRUCTIONS.md gets written to the right place with the right content, and it fails at exactly the expected point (missing OPENROUTER_API_KEY, which is a real secret in the actual CI environment, not present here). Co-Authored-By: Claude Sonnet 5 --- .github/workflows/docs-generate.yml | 35 ++++++++++++++++++++++++----- packages/docs-gen/README.md | 17 +++++++++++++- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/.github/workflows/docs-generate.yml b/.github/workflows/docs-generate.yml index 33c1652..9eb1f08 100644 --- a/.github/workflows/docs-generate.yml +++ b/.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). diff --git a/packages/docs-gen/README.md b/packages/docs-gen/README.md index 648b5ea..5f333a3 100644 --- a/packages/docs-gen/README.md +++ b/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 From 680cd9eae61ed31d5d66c9c2df410b390e3db85b Mon Sep 17 00:00:00 2001 From: CrewCircle Date: Wed, 29 Jul 2026 15:29:33 +1000 Subject: [PATCH 2/4] =?UTF-8?q?Switch=20default=20model=20=E2=80=94=20incl?= =?UTF-8?q?usionai/ling-2.6-flash=20is=20rate-limited?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Confirmed via a real CI run (git-based distribution branch): the literal-cheapest model choice hits a persistent 429 from its backing provider, Novita's shared non-BYOK pool. Happened twice in a row, not transient. Switched to mistralai/mistral-nemo — a first-party lab on OpenRouter rather than a shared-pool aggregation, negligibly pricier ($0.019/$0.03 vs $0.01/$0.03 per M tokens), same tool-calling support. Co-Authored-By: Claude Sonnet 5 --- packages/docs-gen/README.md | 16 ++++++++++------ packages/docs-gen/src/defaults.ts | 2 +- 2 files changed, 11 insertions(+), 7 deletions(-) diff --git a/packages/docs-gen/README.md b/packages/docs-gen/README.md index 5f333a3..c831f7d 100644 --- a/packages/docs-gen/README.md +++ b/packages/docs-gen/README.md @@ -37,12 +37,16 @@ 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 +Defaults to `mistralai/mistral-nemo` via OpenRouter. The literal cheapest +tool-calling-capable model on OpenRouter's catalog at the time this was +written was `inclusionai/ling-2.6-flash`, but a real CI run hit a persistent +`429` from its backing provider (Novita's shared, non-BYOK pool — "temporarily +rate-limited upstream", twice in a row, not a one-off) — see git history on +this file for the failed run. Mistral is a first-party lab on OpenRouter +rather than a shared-pool aggregation, and costs negligibly more +($0.019/$0.03 per M tokens vs $0.01/$0.03), 128k context, tool-calling +supported. 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. diff --git a/packages/docs-gen/src/defaults.ts b/packages/docs-gen/src/defaults.ts index 43c176f..9002271 100644 --- a/packages/docs-gen/src/defaults.ts +++ b/packages/docs-gen/src/defaults.ts @@ -5,7 +5,7 @@ */ export const DEFAULT_ENV: Record = { OPENWIKI_PROVIDER: "openrouter", - OPENWIKI_MODEL_ID: "inclusionai/ling-2.6-flash", + OPENWIKI_MODEL_ID: "mistralai/mistral-nemo", OPENWIKI_TELEMETRY_DISABLED: "1", }; From bfd1ce197784c5a122588779d6c518f5f5491d46 Mon Sep 17 00:00:00 2001 From: CrewCircle Date: Wed, 29 Jul 2026 15:36:50 +1000 Subject: [PATCH 3/4] =?UTF-8?q?Try=20a=20stronger=20model=20=E2=80=94=20mi?= =?UTF-8?q?stral-nemo=20skipped=20generation=20entirely?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first successful run with mistral-nemo produced only a skeleton openwiki/index.md ("# Files", no content) and no other pages. Its own reasoning trace: it looked at recent git log (my session's unrelated commits), incorrectly concluded the wiki was "already current", and never did the actual documentation pass — despite openwiki/ not existing before this run at all. Testing whether a moderately stronger model (qwen3-30b, still cheap, 262k context) follows OpenWiki's own init-vs-update decision logic more reliably. If this also produces a stub, the real fix is likely in docs-gen's own CLI (it pre-creates openwiki/INSTRUCTIONS.md before invoking openwiki, which may itself be enough to make openwiki think a wiki partially exists and take the incremental-update path instead of full generation). Co-Authored-By: Claude Sonnet 5 --- packages/docs-gen/src/defaults.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/docs-gen/src/defaults.ts b/packages/docs-gen/src/defaults.ts index 9002271..bad6b4c 100644 --- a/packages/docs-gen/src/defaults.ts +++ b/packages/docs-gen/src/defaults.ts @@ -5,7 +5,7 @@ */ export const DEFAULT_ENV: Record = { OPENWIKI_PROVIDER: "openrouter", - OPENWIKI_MODEL_ID: "mistralai/mistral-nemo", + OPENWIKI_MODEL_ID: "qwen/qwen3-30b-a3b-instruct-2507", OPENWIKI_TELEMETRY_DISABLED: "1", }; From cb5c2d95aa99dd3159353884814cfeb3cdbc6ba3 Mon Sep 17 00:00:00 2001 From: CrewCircle Date: Wed, 29 Jul 2026 16:00:13 +1000 Subject: [PATCH 4/4] Document qwen3-30b as the verified working model Confirmed via a real, successful CI run: full first-pass generation producing accurate, substantive documentation (openwiki/quickstart.md correctly summarized the actual admin architecture from AGENTS.md). Co-Authored-By: Claude Sonnet 5 --- packages/docs-gen/README.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/packages/docs-gen/README.md b/packages/docs-gen/README.md index c831f7d..d0992e7 100644 --- a/packages/docs-gen/README.md +++ b/packages/docs-gen/README.md @@ -37,19 +37,29 @@ CrewCircle GitHub org secret). ## Model choice -Defaults to `mistralai/mistral-nemo` via OpenRouter. The literal cheapest -tool-calling-capable model on OpenRouter's catalog at the time this was -written was `inclusionai/ling-2.6-flash`, but a real CI run hit a persistent -`429` from its backing provider (Novita's shared, non-BYOK pool — "temporarily -rate-limited upstream", twice in a row, not a one-off) — see git history on -this file for the failed run. Mistral is a first-party lab on OpenRouter -rather than a shared-pool aggregation, and costs negligibly more -($0.019/$0.03 per M tokens vs $0.01/$0.03), 128k context, tool-calling -supported. 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. +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