* fix(ci): move the EPUB build out of pre-commit into CI
The build-epub hooks called scripts/build_epub.py, which raises when the
mmdc binary is missing, while check_mermaid.py skips with a warning in the
same situation. On arm64 — where @mermaid-js/mermaid-cli has no working
build — that made 'pre-commit run --all-files' impossible to satisfy for a
docs-only change without --no-verify.
Remove the build-epub, vietnamese-build-epub and japanese-build-epub hooks
and widen the CI build-epub job to a language matrix so PR-time coverage is
not reduced: it previously built en only, and now builds en, vi, zh and ja.
zh was covered by neither the hooks nor this job, so a broken zh diagram
could only surface at release time.
Closes#156
* docs: replace the stale Kroki narrative with local mmdc rendering
Commit e76bbe4 swapped the Kroki HTTP dependency for local mmdc rendering
but left the docs describing the old design. The claim appeared in seven
live files, not the two originally reported: CLAUDE.md, scripts/README.md
and their ja/uk/vi copies.
Also corrects what the same staleness dragged along:
- scripts/README.md documented --timeout and --max-concurrent, which no
longer exist, and omitted --mmdc-path, --lang and --puppeteer-config
- 'Async concurrent fetching' described a render_all() that is now a plain
sequential loop with a dedupe cache
- the network-error/rate-limiting troubleshooting entries are replaced with
the failures that actually occur now (missing mmdc, Chromium sandbox)
CHANGELOG entries recording the Kroki-to-mmdc switch are left alone; they
describe the past accurately.
Closes#157
* fix(scripts): make the ruff config match files that exist
Ruff resolves include/per-file-ignores patterns relative to the directory
holding pyproject.toml. Since the config lives in scripts/, the pattern
"scripts/**/*.py" meant scripts/scripts/**/*.py, which matches nothing —
'ruff check scripts/' printed 'warning: No Python files found under the
given path(s)' and then 'All checks passed!'. per-file-ignores had the same
mistake. Both are now relative to scripts/, so ruff sees all 14 files.
This silently disabled the pre-commit ruff hooks too, not just the
documented command, and two test files had drifted out of format as a
result. Reformatting them exposed a second problem: the pre-commit hook
pinned ruff v0.8.2 while the CI lint job installs unpinned latest and this
venv has 0.15.10. The versions disagree on formatting, so each reverted the
other's output, and CI would have started failing on a file the local hook
kept rewriting. Bump the hook pin and the requirements-dev floor to 0.15.10
so all three agree.
Verified: 'pre-commit run --all-files' is stable across consecutive runs,
'ruff format --check scripts/' and 'ruff check scripts/' both pass, 92
tests pass.
Closes#160
* docs: point localized module links at their own trees
Files at the root of a language directory used ../NN-module/, which from
uk/CATALOG.md resolves to the English 05-mcp/ at the repo root rather than
uk/05-mcp/. Readers following a count stated about the localized tree
landed in the English one. The link checker never caught it because the
English target does exist.
Files one level deeper (uk/04-subagents/README.md and friends) were already
correct — ../06-hooks/ from there resolves to uk/06-hooks/ — so this is
scoped to the 7 depth-1 files that actually escape: CATALOG.md in uk, vi,
ja and zh, LEARNING-ROADMAP.md in uk and vi, and ja/claude_concepts_guide.md.
119 links in total.
The ../NN- occurrences left in STYLE_GUIDE.md and TRANSLATION_NOTES.md are
inside fenced examples showing what a module page should contain, where the
../ form is the correct convention. All 119 rewritten targets were verified
to exist.
Closes#158
* docs(hooks): stop conflating hook types with hook event categories
'**Hook Types** (5 types, 31 events)' sat above four bullets, so the count
read as wrong. It was not — the two numbers describe different axes that
had been merged into one label.
06-hooks/README.md:126 documents five hook *types*: command, http, prompt,
mcp_tool and agent. Those describe how a hook runs. The four bullets are
event *categories* — Tool, Session, Task, Lifecycle — holding 31 events
(6+7+6+12), and describe when it runs.
Split the label so each number belongs to the axis it counts, in all nine
affected files: README.md and INDEX.md plus the ja, uk, vi and zh copies.
QUICK_REFERENCE.md and LEARNING-ROADMAP.md already stated '5 types' with
the handler names attached and needed no change.
Closes#159
* chore(scripts): drop the unused httpx dependency
httpx was the HTTP client for Kroki rendering. Nothing has imported it
since e76bbe4 moved diagram rendering to a local mmdc subprocess —
check_links.py, the only other network caller, uses stdlib urllib.request.
The PEP 723 blocks in build_epub.py and build_website.py had already
dropped it; only the manifests and docs still declared it.
Removes it from requirements.txt, pyproject.toml dependencies, the
dependency tables and uv --with lines in scripts/README.md and its ja/uk
copies, and the .cspell.json word list. Also drops the B113 bandit
suppression, which existed solely for an httpx timeout false positive —
bandit reports no issues without it.
Also corrects two Requirements lines missed in the previous pass: the ja
and uk script READMEs still listed an internet connection rather than mmdc.
Note: tenacity is now dead for the same reason and is left in place.
* chore(scripts): drop the unused tenacity dependency
Nothing imports tenacity — the retry logic it was added for went away
with the Kroki HTTP fetching in e76bbe4. It was still declared in
requirements.txt, pyproject.toml, both `uv run --with` lines and all
three dependency tables.
* docs(i18n): sync the localized pre-commit check lists
The ja/uk/vi CLAUDE.md files still listed build-epub as pre-commit
check #5, stale since 6da8184 moved the EPUB build to CI. They also
omitted markdown-rendering, and the ja/uk stated counts disagreed with
their own lists. Now matches the English CLAUDE.md.
* fix(scripts): silence PLR0917 now stable in ruff 0.16
CI installs the latest ruff (uv pip install ruff, unpinned), and 0.16.1
promoted too-many-positional-arguments from preview to stable, hard-failing
the Code Quality check on build_epub.py's long-signature draw/helper
functions. These sit in the same family as PLR0913, which is already
ignored. Add PLR0917 so the local 0.15.10 pin and unpinned CI lint agree
again.
Internal accuracy pass against v2.1.220 — no missing upstream features, but broken example code, disagreeing counts, and metadata drift.
Functional fixes: pre-commit.sh now exits 2 so it actually blocks; dependency-check.sh reads file_path from stdin JSON instead of $1; database-mcp.json uses ${DATABASE_URL}; broken fences repaired; three command templates had invalid skill names.
Factual corrections: /fork and /subtask unswapped and /subtask added; /fewer-permission-prompts; permissions.defaultMode; dontAsk/auto unreversed; 31 hook events verified name-by-name; subagent depth 3; skill precedence enterprise > project > personal; /output-style removed not deprecated; permissionDecision gained defer.
Follow-up review fixed defects the pass left behind: zh/vi headers claiming 31 events above 25-name lists, a surviving hardcoded DB credential in the MCP README examples, an unbalanced fence swallowing a metadata footer, and non-canonical tool names. All four translated CATALOG summary tables were recounted so their arithmetic holds.
Full detail in CHANGELOG.md under v2.1.220-r2.
Bumps tutorial coverage from the v2.1.217 baseline (2026-07-22 sync) to
v2.1.220 — three contiguous releases (v2.1.218–v2.1.220).
Critical fixes:
- Nested subagent spawning is on by default again at depth 3 (v2.1.219).
Five locations across 04-subagents, CATALOG, 10-cli and QUICK_REFERENCE
stated it was disabled by default — true for v2.1.217–v2.1.218 only.
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 now disables rather than enables.
All five carry an identical three-era history note.
- Claude Opus 5 is the default Opus model (v2.1.219). 10-cli asserted
"Opus 4.8 remains the default"; Opus 5 was absent from every model table.
Added to both model tables, 19 Compatible Models footers, and ~20
effort-level enumerations.
Also fixed: fast-mode model list, auto-mode eligibility self-contradiction
in 09-advanced-features, stale CLAUDE_CODE_ENABLE_AUTO_MODE opt-in in
CATALOG, hook-event count disagreement (29/30 -> 31 across three files),
doc-generator skill name/directory mismatch, stale "May 2026" headings,
and the last three docs.anthropic.com links.
Added: DirectoryAdded hook, /deep-research explicit-invocation note,
/code-review background subagent, context:fork background default, agent
frontmatter hook workspace trust, dynamic workflow size guideline and
workflowSizeGuideline key, sandbox.network.strictAllowlist, MCP error
surfacing, stream-json nested subagent forwarding, frontmatter boolean
values, agent name ':' rejection, auto/plan-mode classifier changes, and
Opus 5 safety-classifier fallback.
Renamed the deep-research skill example to topic-research to stop it
shadowing the built-in; mirrored to vi/ja/uk. doc-generator rename
mirrored to ja/zh/uk.
The JSON example in the installation section had a trailing comma after
the hooks object, making it invalid JSON. This prevents users from
copy-pasting the configuration successfully.
Bumps tutorial coverage from the v2.1.212 baseline (2026-07-18 sync) to
v2.1.217 (v2.1.213 was skipped upstream), plus a repo-internal accuracy
audit.
Fixed:
- Nested-subagent-spawning claim reversed (v2.1.217): 04-subagents/README.md
and CATALOG.md stated nesting up to 5 levels as current behavior; as of
v2.1.217 it's off by default, opt in via CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH
- Stale --enable-auto-mode flag (removed in v2.1.111) replaced with
--permission-mode auto across 10-cli/README.md and QUICK_REFERENCE.md
- Import-depth contradiction in 02-memory/README.md: two remaining "5 levels"
instances corrected to "4 hops", matching the rest of the file
- Sonnet 5 added to claude_concepts_guide.md's models/reasoning-effort table
- config-examples.json's fabricated settings schema (fake "unrestricted"/
"confirm" modes, undocumented keys) rewritten to real settings.json keys
- brand-voice skill (name/user-invocable) aligned to its README worked example
- CLAUDE.md length guidance unified across 03-skills/claude-md/SKILL.md and
02-memory/README.md
Added:
- New subagent caps (v2.1.217): CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS
- --max-budget-usd now also halts running background subagents (v2.1.217)
- Hook if: glob scope narrowed to <cwd>/dir (v2.1.214), documented in
06-hooks/README.md along with SessionStart's new "fork" source
- sandbox.filesystem.disabled setting (v2.1.216)
- /rewind symlink/hard-link protection (v2.1.216)
- Auto-memory modified timestamp (v2.1.214) and non-blocking /memory editor
(v2.1.216)
- CLI/settings batch (v2.1.214-217): emojiCompletionEnabled,
FORCE_HYPERLINK=0, CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH, --settings 2 MiB
cap, permission hardening notes, /context and /compact notes
- /verify and /code-review explicit-invocation-only note (v2.1.215)
Mirrored applicable P0/P1 fixes into vi/ja/zh/uk translations where the
same claim existed.
* docs: sync to Claude Code v2.1.212
Bumps tutorial coverage from the v2.1.206 baseline (2026-07-11 sync) to
v2.1.212, plus a repo-internal accuracy audit that surfaced defects
independent of the version delta.
Fixed:
- Dead `#` memory-shortcut removed from 02-memory/README.md (two places
documented a discontinued quick-memory-add pattern as working, directly
contradicting the file's own commands table)
- Auto mode opt-in -> opt-out on Bedrock/Vertex/Foundry (v2.1.207)
- `auto` permission mode mislabeled "Research Preview" across
09-advanced-features/README.md, CATALOG.md, README.md, and the vi/ja/zh/uk
translations (auto mode is GA, gated only by plan/model/provider)
- `/fork` / `/branch` history corrected: they were a single aliased command
only from v2.1.77 to v2.1.161, not "renamed" as previously stated
- `effort` frontmatter enum in 04-subagents/README.md completed with `xhigh`
- Bundled-skills count reconciled in CATALOG.md (9 -> 10)
- INDEX.md Skills section count and Feature Coverage Matrix Total column
fully recomputed and reconciled (Skills: 22, Plugins: 39)
- Stale 2.1.160 footer cluster (5 files) bumped to 2.1.212
- QUICK_REFERENCE.md fully resynced (was 52 versions behind)
- 02-memory/README.md's Memory Hierarchy section rewritten: replaced a
fabricated 8-tier strict-precedence model with the verified structure
(CLAUDE.md files are concatenated into context, not overridden; 4 real
location tiers; rules and auto memory are separate mechanisms)
- 02-memory/README.md's Memory Architecture diagram no longer conflates
claude.ai's 24h synthesis cycle with Claude Code's continuous auto memory
- Import recursion depth corrected (was documented as 5, actually 4 hops)
Added:
- Subagent output scanning (v2.1.210) documented in 04-subagents/README.md
- Session-wide spawn caps (v2.1.212): WebSearch and subagent limits
- MCP long-running-tool auto-backgrounding (v2.1.212) in 05-mcp/README.md
- `claude auto-mode reset` and `/resume` picker (v2.1.212)
- Screen reader mode (v2.1.208): --ax-screen-reader / CLAUDE_AX_SCREEN_READER
- Task tool `mode` parameter deprecation note (v2.1.212)
Known gaps (deferred, not fixed this pass):
- 03-skills/blog-draft/ vs 03-skills/.claude/skills/blog-draft/: confirmed
the latter is gitignored local testing scratch, not a repo duplicate
* fix(INDEX): correct Skills row arithmetic and stale changelog notes
INDEX.md's Skills header/matrix shipped as 22 (5+9+8) despite the PR's
own CHANGELOG claiming it was fixed to 21 — three independent counts
(file-type breakdown, filesystem listing, changelog intent) agree on
21; the Docs column was off by one. Also removes two stale CHANGELOG
"Known gaps" entries this same PR already resolved (memory hierarchy
rewrite, blog-draft gitignore confirmation) and adds the missing
Fixed-section bullet documenting the memory hierarchy rewrite.
* docs: correct stale content for Claude Code v2.1.206
Fix content that no longer matches current Claude Code behavior:
- 04-subagents: remove the /agents creation-wizard instructions
(wizard removed in v2.1.198); point users to ask Claude or edit
.claude/agents/ files directly. Explore agent now inherits the
session model (capped at Opus) instead of Haiku; subagents run in
the background by default.
- Rename the default permission mode "default" -> "Manual" (v2.1.200)
across README, CATALOG, INDEX, LEARNING-ROADMAP, resources,
claude_concepts_guide, and 09-advanced-features, noting that
"default" still works as an alias.
- README: update the stale "latest v2.1.160" currency claims to v2.1.206.
- Reconcile the contradictory /simplify vs /code-review history:
they are distinct current skills (/simplify split back out in v2.1.154).
Refresh metadata footers to v2.1.206 / July 11, 2026 and add Claude
Sonnet 5 to Compatible Models on every edited file.
* docs: add Claude Code v2.1.206 feature coverage
Document new features and options that landed through v2.1.206:
- Skills: /dataviz bundled skill, skill stacking (loads all leading
skills, up to 5), and the ${CLAUDE_PROJECT_DIR} substitution.
- Slash commands: /dataviz row and ${CLAUDE_PROJECT_DIR} mention.
- Subagents already covered in the correctness commit; CLI adds
--append-subagent-system-prompt, CLAUDE_ENABLE_STREAM_WATCHDOG,
a Claude Sonnet 5 model row (new default, 1M context), and the
/model "Org default" note.
- MCP: roots/list working-directory discovery and the untrusted-
workspace pending-approval behavior for self-approved .mcp.json.
- Hooks: agent_needs_input / agent_completed Notification values and
the prompt_id input field.
- Plugins: marketplace renames / displayName / defaultEnabled fields.
- Checkpoints: "Summarize up to here" backward targeted compaction.
Refresh metadata footers to v2.1.206 / July 11, 2026 and add Claude
Sonnet 5 to Compatible Models on every edited file.
* docs: qualify Sonnet 5 default scope and reconcile bundled-skills list
- Sonnet 5 default is tier-dependent (Pro/Team seats); Opus 4.8 remains
default on Max/Team Premium/Enterprise PAYG/API — was overstated as
the flat default.
- Add missing /simplify row to the bundled-skills table (it was already
referenced as a distinct skill in the /code-review row) and drop the
hard skill count in favor of pointing at the commands reference.
Cut SKILL.md body ~230 lines by extracting the deep-assessment round
questions, output templates, and topic recommendations into references/
(deep-assessment-rounds.md, output-templates.md, topic-recommendations.md).
Keep the scoring-map table inline for correctness. Rewrite description,
add a worked example and Acceptance Criteria. Normalize frontmatter;
metadata.version 2.3.0 -> 2.4.0.
astral-sh/setup-uv enable-cache defaults to keying off uv.lock, which
this repo intentionally gitignores, so every push to main since
2026-06-17 failed at the cache step before the build ever ran.
* docs: sync to Claude Code v2.1.187
Sync the delta from v2.1.179 to v2.1.187 across six modules.
- slash-commands: reclassify `/review <pr>` as a supported PR-review entry
point (same engine as `/code-review medium`, v2.1.186), no longer deprecated
- advanced-features: `!` bash output now auto-responds (v2.1.186);
`/config key=value` shorthand + `--help` (v2.1.181/.183) and menu key
behavior; built-in intent-based auto-mode blocks for destructive git/IaC
commands (v2.1.183); `sandbox.credentials` / `sandbox.allowAppleEvents`
- subagents: `teammateMode: "iterm2"` display mode (v2.1.186)
- memory: `attribution.sessionUrl` setting (v2.1.183)
- mcp: `claude mcp login` / `claude mcp logout` CLI auth (v2.1.186)
- cli: `respondToBashCommands` setting; new env vars
`CLAUDE_CLIENT_PRESENCE_FILE`, `CLAUDE_CODE_MAX_RETRIES` (cap 15),
`CLAUDE_CODE_RETRY_WATCHDOG`, `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`
Footers on all touched files bumped to v2.1.187.
* fix(advanced-features): correct respondToBashCommands version framing
The ! bash auto-response feature landed in v2.1.186 (confirmed against the
official changelog). The previous 'Since v2.1.187 (changed in v2.1.186)'
wording was misleading and inconsistent with 10-cli/README.md, which
correctly tags respondToBashCommands as v2.1.186.
Optimize the lesson -> GitHub Pages conversion in build_website.py:
- BS4 single parse: thread one BeautifulSoup tree through heading-id
normalisation, TOC extraction, and link rewriting instead of
reparsing the rendered HTML 3x per page. Build drops 2.97s -> 1.77s
(~40% faster) on the ~222-page site; html.parser reparsing was the
dominant cost.
- Nav O(n^2) -> O(n): build the sidebar section grouping once
(build_nav_skeleton) and resolve per-page relative URLs in localize_nav,
removing ~49k redundant relative_link/grouping calls.
- Read each .md once: cache source text on PageInfo.content and reuse it
across collect_pages, render_pages, and copy_assets (was 2-3 reads/page).
- CI: enable uv cache and cache scripts/.vendor-cache so deploys skip cold
dep resolution and vendor (Tailwind/Mermaid/fonts) downloads.
Public string APIs (derive_page_title, render_markdown, extract_toc,
rewrite_links, normalise_heading_ids) preserved as thin wrappers over the
new soup-based cores. Full suite green (92 tests), ruff/mypy clean.
Output is semantically identical to the prior build; the only diff is raw
hand-written <img/> badges serializing as <img></img> (valid HTML5,
renders identically; nothing validates generated site HTML).
Additive sync over v2.1.176 baseline. No breaking changes, removals, or
deprecations in the v2.1.177-v2.1.179 window (v2.1.177 is a chore-only
release; v2.1.179 is bugfix-only plus a plugin perf note).
New in v2.1.178:
- 10-cli: document generalized Tool(param:value) parameter-matching
permission syntax (cites permissions reference for per-tool examples)
- 03-skills: nested .claude/skills/ collision rule (closest to cwd wins)
- 04-subagents: nested .claude/ precedence for agents/workflows/output-styles
- /doctor flat-tree layout refresh (10-cli, 01-slash-commands)
- /bug now requires a description before submit (01-slash-commands)
New in v2.1.179:
- 07-plugins: improved plugin loading performance in remote sessions
Footers on all five edited files bumped to v2.1.179 / June 17, 2026.
* docs: sync to Claude Code v2.1.176
Fix the subagent-nesting self-contradiction in 04-subagents and document
additive features shipped in v2.1.172-v2.1.176:
- 04-subagents: subagents can now spawn subagents (up to 5 levels, v2.1.172),
replacing the stale "no nested spawning" line; footer bumped to 2.1.176
- 07-plugins: /plugin marketplace search bar (v2.1.172)
- 10-cli: new settings.json keys wheelScrollAccelerationEnabled,
footerLinksRegexes, language (v2.1.174-v2.1.176)
- 09-advanced-features: enforceAvailableModels managed setting (v2.1.175)
- 06-hooks: if-condition tool-argument path matchers (verified against the
official permissions reference)
- claude_concepts_guide & CATALOG: subagent nesting note + VSCode /usage
attribution breakdown (v2.1.174)
* fix(10-cli): correct language setting scope and fix link-checker false positive
- check_links.py: skip bare-hostname captures (no dot in host) that URL_RE
truncates from regex strings in JSON config examples, e.g.
"https://jira\\.example\\.com/.*" was captured as "https://jira" and
flagged as a dead link in CI strict mode. Dotted hosts (real URLs) and
SKIP_DOMAINS single-label hosts are unaffected, so no link coverage is lost.
- 10-cli/README.md: language is Claude's general response/voice-dictation
language setting (e.g. french/japanese), which v2.1.176 also wired to
session-title generation — not a session-titles-only key. Updated the
description and the JSON example value to match the official settings docs.
* chore(idd): exempt docs-sync PRs from traceability Closes #N requirement
Adds .gitissue.yml so 'docs: sync to Claude Code vX' PRs (which aren't tied to
a single tracked issue) are not hard-blocked on a missing Closes #N — they opt
in via a 'Type: docs' body line, matching how chore/refactor PRs work. The
other three traceability checks still run.
Mirror the English fix from #131 into the translated docs. The precedence
table in 02-memory and the v2.1.119 /config notes still encoded the old,
incorrect order (user above project/local).
- vi/02-memory: table rows -> local(3) -> project(4) -> user(5, lowest)
- ja/02-memory: table rows reordered + /config note policy/local/project
- ja/10-cli: /config note chain -> policy -> local -> project -> user
- uk/02-memory: table rows reordered
Correct order per https://code.claude.com/docs/en/settings:
Managed -> CLI args -> Local -> Project -> User (lowest).
zh is missing the whole settings section (structural port), tracked
separately in #132.
Refs #132
- 10-cli/README.md: policy → local → project → user (was project → local → policy → user)
- 02-memory/README.md: reorder table levels 3/4/5 to local → project → user
- 02-memory/README.md: update note text to match corrected order
* docs: sync to Claude Code v2.1.156 and Claude Opus 4.8
Model bump Opus 4.7 -> Opus 4.8 and version sync v2.1.150 -> v2.1.156.
- Rewrite effort-ladder claims for Opus 4.8 (default `high`; `xhigh` on
4.8/4.7; `max` on 4.8/4.7/4.6 and Sonnet 4.6; Haiku has no effort).
- Replace soon-removed CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE with the
`/model claude-opus-4-6[1m]` + `/fast on` path; note Opus 4.8 fast mode.
- Bump lineup tables to Opus 4.8; fix Haiku 4.5 context (1M -> 200K).
- Sweep Compatible Models + version/date footers to 2.1.156 / May 29, 2026
across 23 English docs (incl. 2.1.138/2.1.145 stragglers).
- Re-document `/simplify` as a distinct cleanup-only command (v2.1.154).
- Add Dynamic Workflows + `/workflows`, MessageDisplay hook (count 29->30),
disallowed-tools frontmatter, `/reload-skills` + SessionStart outputs,
`/model` default-save inversion, lean system prompt, status-line
COLUMNS/LINES, and the ultracode `/effort` note.
* docs(cli): drop unverified fast-mode dollar pricing, keep verified rate/speed multipliers
* fix(i18n): re-point translations to code-review-specialist rename
The English code-review skill was renamed to code-review-specialist in #127
to avoid shadowing the new built-in /code-review command. Mirror that rename
across the uk, vi, ja, zh locales: rename each 03-skills/code-review/ directory
to code-review-specialist/, update the i18n-source markers in the moved ja
files, and fix path references in INDEX.md, QUICK_REFERENCE.md, and the vi
TRANSLATION_QUEUE.md.
* chore: ignore .asm-improver and .gitissue tooling state
* fix(i18n): re-point remaining code-review install paths to code-review-specialist
Follow-up to #123 — that PR fixed module README logo paths but missed
root-level translated files (README, INDEX, CATALOG, CONTRIBUTING,
STYLE_GUIDE, etc.) which had the same broken-path pattern: they used
`resources/logos/...` (root-relative) but live one directory deep, so
they resolved to `{lang}/resources/logos/...` and 404'd.
Fix: `resources/logos/...` → `../resources/logos/...` in the top
`<picture>` block of each translated root-level file.
For STYLE_GUIDE files, the in-code-fence `<picture>` example was left
as `resources/logos/...` to mirror the English source — it documents
the canonical pattern, not the path the file itself uses.
Files: zh/ (×9), uk/ (×4), vi/ (×2). ja/STYLE_GUIDE.md was already
correct.
Bumps tutorial coverage from v2.1.138 → v2.1.143. Highlights:
- /goal and /scroll-speed slash commands (v2.1.139)
- claude agents Agent View (Research Preview) with 9 dispatch flags
- claude plugin details and marketplace context-cost projection
- Hook exec form (args), continueOnBlock on PostToolUse, terminalSequence
- Stop hook 8-block safety cap + override env var
- Fast Mode default flipped to Opus 4.7 (v2.1.142)
- PowerShell tool default-on for Bedrock/Vertex/Foundry on Windows
- API-key auth disables Remote Control, /schedule, claude.ai MCP, notifications
- worktree.bgIsolation setting
- CLAUDE_PROJECT_DIR for MCP stdio servers
- Subagent OTEL headers + case-insensitive subagent_type matching
- Root-level SKILL.md plugin pattern; Routines marketing name note
Also bumps stale "28 hook events" counts in CATALOG/README to 29 and
refreshes the metadata footer (Last Updated, Claude Code Version,
Sources) on every modified file.
* feat(scripts): add static website generator from markdown sources (#85)
Generate an elegant, mobile-friendly static site from the existing
tutorial markdown files. The markdown remains the single source of
truth — `scripts/build_website.py` reads from the same `.md` files the
EPUB builder uses, rewrites cross-references to site URLs, and rewrites
references to non-markdown repo files (`.json`, `.sh`, `.py`) to
GitHub blob URLs so users can jump to the source on github.com.
Highlights:
- Reuses the chapter ordering convention from `build_epub.py`
- Anchor algorithm mirrors `check_cross_references.heading_to_anchor`
for parity with the validator
- Mermaid renders client-side via `mermaid.js` (no pre-render step)
- Tailwind CSS via CDN; light/dark theme toggle; sidebar nav; in-page
TOC; prev/next page navigation; mobile responsive
- 27 unit + smoke tests covering anchors, link rewriting (including
`<source srcset>` inside `<picture>`), Mermaid handling, and a full
end-to-end build
- GitHub Pages deploy workflow at `.github/workflows/pages.yml`
Closes#85
* fix(website): use relative URLs in sidebar nav and avoid INDEX.html collision
Two bugs found by local browser dogfooding:
1. **Sidebar nav broke from deep pages.** `build_navigation` emitted raw
`output_url` values (site-root-relative) which made every sidebar link
404 from any page below the root. Moved the call inside the per-page
render loop so each page gets nav links computed relative to its own
URL — `01-slash-commands/index.html` from the root, `../01-slash-commands/...`
from a depth-1 page, `../../01-slash-commands/...` from depth-2.
2. **`INDEX.md` overwrote `index.html`.** On case-insensitive filesystems
(macOS/Windows), `INDEX.html` and `index.html` are the same file, so
`INDEX.md` clobbered the rendered `README.md`. Added `_disambiguate_url`
that detects case-insensitive collisions and suffixes the colliding
page with its source stem (`INDEX-index.html`).
Added 2 tests; full suite stays at 83 passed.
* fix(scripts): skip URLs with port in localhost/127.0.0.1 skip list
`check_links.is_skipped()` did an exact-match comparison against the
host, so `http://localhost:8080` (used in scripts/README.md as a preview
example) was not skipped and CI's link check tried to fetch it, which
fails on the GitHub runner. Strip the port before comparing.
* chore(scripts): drop vestigial mypy ignore_errors for build_website
The override silenced all mypy errors for build_website, making the
"mypy: clean" claim technically vacuous. Removing it shows mypy is
actually clean — 0 issues on build_website after type annotations
were added during PR review.
* feat(website): self-host Tailwind, Mermaid, and Inter fonts
Drop all third-party CDN dependencies from rendered pages. The site
previously loaded Tailwind from cdn.tailwindcss.com (Play CDN — JIT
compile in browser, marked not-for-production), Mermaid from
cdn.jsdelivr.net, and Inter/JetBrains Mono from fonts.googleapis.com.
Replace with a vendored toolchain:
- scripts/vendor_assets.py downloads the Tailwind standalone CLI
(Go binary, no Node toolchain), Mermaid's UMD bundle, and Google
Fonts CSS + WOFF2 files. Cached under scripts/.vendor-cache/
(gitignored), refetched only when missing.
- Tailwind compiles a per-build site/assets/tailwind.css with only
the utility classes actually used by the rendered HTML.
- Mermaid and font files land in site/assets/vendor/ and load via
relative URLs.
- Tailwind config + entry CSS live in scripts/website_templates/
alongside the Jinja template.
- build_website grows a skip_vendor flag so the smoke test runs
offline.
- pre-commit mypy hook gets types-Markdown so it can resolve the
same imports as the project venv.
Verification: 86/86 pytest pass, ruff/mypy/bandit clean, full
build produces a working site with zero external requests (verified
in a headless browser — no console errors, no failed network calls,
Mermaid diagrams render).
* fix(website): use tree URLs for repo directory links (#85)
* fix(website): include additional top-level docs (#85)
Catches mechanical rendering bugs that look fine in a diff but render
wrong on GitHub / in the EPUB build: inner backticks inside inline-code
spans (PR #114), unescaped pipes in table cells (PR #115), stray
`$ARGUMENTS` outside code, and unmatched fences.
Scope: `**/README.md` across tutorial modules + translations (ja, uk,
vi, zh). Excludes dev tooling dirs (`.claude`, `.venv`, `openspec`, …).
Rule registry: each rule is `(Path, content) -> list[str]`. Adding a
new rule = one function + one registry entry + one test fixture.
- scripts/check_markdown_rendering.py: 4 rules, CommonMark-aware code-
span consumption, blockquote-fence-aware masking
- scripts/tests/test_check_markdown_rendering.py: 20 unit tests,
positive + negative per rule, currency-false-positive guard
- .pre-commit-config.yaml: new global `markdown-rendering` hook
Escape backticks across en/ja/uk/vi/zh slash-commands and skills modules so the literal `!`command`` syntax renders correctly instead of breaking the inline-code span.
Documents the v2.1.131 → v2.1.138 sync (PR #117) in the same format
as the v2.1.131 entry. Pattern caught during release-manager review;
the original sync PR did not include a CHANGELOG update.
Sync covers v2.1.128, v2.1.129, and v2.1.131 (May 2026). Highlights:
gateway /v1/models discovery is now opt-in (CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY),
added --plugin-url flag, disableRemoteControl setting, /mcp tool-count display,
expanded skillOverrides values, /context viz no longer leaks into conversation,
Ctrl+R cross-project default. Also reconciles slash-command count to 60+ and
fixes the skill-count entry in CATALOG.
The lesson-quiz skill had two issues:
1. Correct answers were always placed as the first option, making quizzes
trivially solvable
2. No feedback was given after each round — users had to wait until all
5 rounds were complete to see any results
Add a CRITICAL shuffle instruction requiring randomized option order for
each question, and update round flow to show immediate per-question
feedback after each round.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The code-review skill had templates/ and scripts/ directories alongside
SKILL.md, but SKILL.md never referenced them. Since Claude Code only
loads SKILL.md when a skill is invoked, the supporting files were
effectively invisible. This adds a Reference Files section that
instructs Claude to read and use each supporting file.
Closes#43
Co-authored-by: Paperclip <noreply@paperclip.ing>
- Replace fictional `/think` example with official `ultrathink` keyword
- Fix Q4 options: `/think` → `/effort max`, `--thinking` → `ultrathink`
- Fix Q5: correct the answer that "ultrathink" DOES trigger deep reasoning
- Sync changes across English, Ukrainian, and Vietnamese translations
Background: `/think` is not a valid slash command in Claude Code (verified
against official commands reference at code.claude.com/docs/en/commands).
The correct way to trigger deep reasoning for a single response is to
include "ultrathink" in the prompt.
Sources:
- https://code.claude.com/docs/en/commands (no /think command exists)
- https://code.claude.com/docs/en/model-config (ultrathink is valid keyword)
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
The lesson quiz Q2 had `#` prefix as the correct answer for adding
memory rules, but the lesson README explicitly states this was
discontinued. Update answer to `/memory` or conversational request,
and fix a residual `#` prefix reference in the README's "Quick
update workflow" section.
Closes#106
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Remove the specific 21,800+ stars and 2,585+ forks numbers across en/zh/ja
READMEs. They go stale within a day of every commit. The Star History chart
already conveys current scale, and the trust bullets read fine without exact
counts.
- Backfill CHANGELOG.md with v2.4.0 entry summarizing the
v2.1.112 → v2.1.119 sync work
- Refresh SECURITY.md footer (Last Updated April 27, 2026;
Next Review April 2027)
- Fix model ID in 09-advanced-features/config-examples.json:
claude-opus-4 → claude-opus-4-7 (3 occurrences) for
consistency with documented model IDs
- Remove RELEASE_NOTES.md stub that duplicated and contradicted
CHANGELOG.md
Closes#99
- Replace shell-interpolated JSON build with the argv-based Python pattern
from session-end.sh, so notes containing quotes or backslashes don't
produce invalid JSON.
- Add mkdir/cp/chmod install block before the Configuration section so
the path in settings.json resolves to a real file.
