Skip to content

Explicit onBrokenAnchors, doctor target argument, and accurate config guidance - #1

Merged
ThisIsTJ merged 3 commits into
mainfrom
feat/broken-anchors
Aug 21, 2026
Merged

ThisIsTJ merged 3 commits into
mainfrom
feat/broken-anchors

Conversation

@ThisIsTJ

Copy link
Copy Markdown
Collaborator

Three changes, all surfaced while migrating a fourth workshop (case management) onto the kit. Releases as v1.2.0.

onBrokenAnchors set explicitly

onBrokenLinks already covers links between pages; this is the in-page equivalent. Set to 'warn', which is also the Docusaurus default, so this changes no behaviour today — it makes the choice visible and gives one place to tighten it later.

Deliberately not 'throw': a stale anchor is a content bug, not a reason to block a deploy on the morning of a workshop. The tradeoff is that a green exit code no longer means the anchors are clean — the warning only appears in build output.

This replaces a hand-rolled 39-line postbuild script the case management workshop carried, which walked build/docs/**/*.html to reimplement the same check. That script did fail the build; nothing does now. That is a deliberate reduction in enforcement, recorded in TODO.md.

Verified by planting a link to a non-existent anchor: Docusaurus names the exact page and anchor, and the build exits 0.

doctor accepts a positional target

workshop-kit doctor bellevue-2026 silently ignored the argument and reported the default target, so npm run target:check -- <target> confirmed the wrong tenant while looking like it had confirmed the right one. Worse than erroring, for a command whose whole purpose is to be trusted before a deploy.

build, start and preview already take a positional target via takeTarget(), and getTarget() already accepts an explicit name — doctor just never passed one through.

agents/base.md: the three config surfaces

The shared guidance claimed session-specific workshop values "must come from .env via docusaurus.config.ts customFields.workshop". That described the pre-kit architecture — nothing in the kit reads a plain .env for workshop values. Because base.md is the fenced region of every repo's AGENTS.md, that one wrong line was misleading in all four repos.

Replaced with what actually reads what:

File Read by Committed
config/workshop-targets.json the site and every CLI command yes, participant-visible
.env.deploy.<target> only the codedapp commands no
.env / .env.<target> only the pulse dashboard no

Also records that stray WORKSHOP_UIPATH_* keys in a .env are dead leftovers (coding-agents-workshop still has four), and the target precedence: explicit CLI argument, then WORKSHOP_TARGET, then defaultTarget.

Follow-up required after merge

The fence hash moves 199aad91 -> 35131c9d, so all four repos need npm run prepare:docs to regenerate AGENTS.md as part of their repin to v1.2.0. Repinning without regenerating leaves agents:check failing.

Nothing breaks before then: each repo validates against the base.md in its own pinned kit, confirmed green on all four today.

Tag v1.2.0 and force-move v1 after merge.

Verification

Ran the kit-ci.yml checks locally: npm run validate, every module parses, CLI responds, and the AGENTS.md fence round-trip (including that a tampered fence still fails the check).

🤖 Generated with Claude Code

ThisIsTJ and others added 3 commits August 20, 2026 15:44
A link to a heading that was renamed breaks silently, and workshops accumulate
those as exercises are reordered and retitled. onBrokenLinks already covers
links between pages; this is the in-page equivalent.

Set to 'warn', which is also the Docusaurus default, so this changes no
behaviour today — it makes the choice visible and gives one place to tighten it
later. Deliberately not 'throw': a stale anchor is a content bug, not a reason
to block a deploy on the morning of a workshop. The tradeoff is that the
warning only shows in build output, so a green exit code does not mean the
anchors are clean.

This replaces the hand-rolled 39-line postbuild script the case management
workshop carried, which walked build/docs/**/*.html to reimplement the same
check. That script did fail the build; nothing does now, which is the intended
change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`workshop-kit doctor bellevue-2026` silently ignored the argument and reported
the default target instead, so `npm run target:check -- <target>` confirmed the
wrong tenant while looking like it had confirmed the right one. That is worse
than erroring, since the command exists to be trusted before a deploy.

build, start and preview already take a positional target via takeTarget(), and
getTarget() already accepts an explicit name — doctor just never passed one
through. This wires it up the same way.

Found while migrating the case management workshop, whose pre-kit script did
accept the argument, so its README instructions had quietly become wrong.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The shared guidance said session-specific workshop values "must come from .env
via docusaurus.config.ts customFields.workshop". That described the pre-kit
architecture. Nothing in the kit reads a plain .env for workshop values — they
come from config/workshop-targets.json, which createWorkshopConfig publishes as
customFields.workshop. Because base.md is the fenced region of every repo's
AGENTS.md, that one wrong line was misleading in all four.

Replaced with the actual layout, since the overlap between the files is what
makes this confusing:

  config/workshop-targets.json  participant-visible values; committed; read by
                                the site and by every CLI command
  .env.deploy.<target>          UIPATH_FOLDER_KEY and two optional packaging
                                values; git-ignored; read only by codedapp
  .env / .env.<target>          WORKSHOP_TARGET/START/END and RE_CONTEXT; read
                                only by the pulse dashboard

Also records that WORKSHOP_UIPATH_* keys sitting in a .env are dead leftovers
(coding-agents-workshop still has four of them), and the target precedence:
explicit CLI argument, then WORKSHOP_TARGET, then defaultTarget.

The fence hash moves from 199aad91 to 35131c9d, so every repo needs
`npm run prepare:docs` when it repins. No repo breaks before then: each checks
against the base.md in its own pinned kit.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ThisIsTJ
ThisIsTJ merged commit 04b56c4 into main Aug 21, 2026
1 check passed
@ThisIsTJ
ThisIsTJ deleted the feat/broken-anchors branch August 27, 2026 18:38
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant