* 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.
* 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.
* 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
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.
Sync all English tutorials with Claude Code v2.1.112 and the new Opus 4.7
model (claude-opus-4-7). Introduces the xhigh effort level (new default on
Opus 4.7), two new built-in slash commands (/ultrareview,
/less-permission-prompts), auto mode without --enable-auto-mode for Max
subscribers on Opus 4.7, PowerShell tool on Windows, Auto-match-terminal
theme, and plan files named after prompts. All 18 EN doc footers bumped to
Claude Code v2.1.112.
Version callouts in README.md, zh/README.md, and uk/README.md updated to
v2.1.112. Changelog entry prepended.
Repo version now tracks Claude Code version (2.3.0 → 2.1.112 is intentional
per new convention).
* docs: sync to Claude Code v2.1.101 with new feature coverage
Bumps all English docs from v2.1.97 to v2.1.101, adds mandatory Sources
footer block (previously missing), and documents three new features
shipped between v2.1.98 and v2.1.101:
- /team-onboarding (v2.1.101) — new built-in command for generating
teammate ramp-up guides. Added to 01-slash-commands and CATALOG.
- /ultraplan (v2.1.91+, cloud-env auto-creation in v2.1.101) — full
section in 09-advanced-features covering launch methods, status
indicators, and execution options. Replaces prior 3-line stub.
- Monitor tool (v2.1.98) — full section in 09-advanced-features with
stream-filter and poll-emit patterns and the grep --line-buffered
warning. Added to resources.md feature table.
Vietnamese and Chinese translations are not touched in this sync.
* fix(docs): address review feedback on v2.1.101 sync
- Correct /team-onboarding availability date (April 10 → April 11, 2026)
- Fix uninitialized \$last variable in Monitor poll-and-emit example
- Update CATALOG.md New Features heading to April 2026 and add Monitor
Tool, /team-onboarding, and Ultraplan auto-create entries
The latest Claude Code release is 2.1.97, not 2.3.0 (which is this
guide's own version). Update all 20 "Claude Code Version" footer lines
to accurately reflect the documented Claude Code version.
Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
Update all documentation footers from generic "April 2026 / 2.1+" to
the specific sync date (April 9, 2026) and documented version (2.3.0).
Also add version/date footers to zh/CATALOG.md and
zh/01-slash-commands/README.md which were missing them.
Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>
* docs: sync all tutorials with latest Claude Code official docs (April 2026)
Update 44 documentation files to reflect the latest Claude Code features
from code.claude.com. Key content changes include new slash commands
(/ultraplan, /powerup, /sandbox), deprecated command removals (/pr-comments,
/vim), corrected skill description budget (1%/8K), new hook events
(PermissionDenied, InstructionsLoaded, ConfigChange), expanded Agent Teams
section, new plugin components (LSP, bin/, settings.json), and new CLI
flags (--bare, --tmux, --effort, --channels). Added "Last Updated: April
2026" metadata footer to all documentation files.
* fix(docs): correct env var values and alphabetical ordering
- CLAUDE_CODE_NEW_INIT=true → =1 in 02-memory and 09-advanced-features
- CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true → =1 in 09-advanced-features
- Fix /powerup vs /plugin alphabetical order in slash commands table
* fix(docs): correct env var values in locale files (vi, zh)
Propagate CLAUDE_CODE_NEW_INIT=true → =1 and
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true → =1 corrections
to Vietnamese and Chinese translations.
Update 23 files across all 10 tutorial directories and 7 reference
documents to match the latest Claude Code v2.1+ features and correct
outdated content including model names (4.5→4.6), permission modes,
hook events, CLI syntax, MCP config paths, plugin manifest format,
checkpoint commands, session management, and URLs. Add documentation
for new features: Auto Memory, Remote Control, Web Sessions, Desktop
App, Agent Teams, MCP OAuth, Task List, Sandboxing, and more.
- Update all main markdown files (INDEX.md, LEARNING-ROADMAP.md, QUICK_REFERENCE.md, CONTRIBUTING.md, claude_concepts_guide.md, resources.md) with new responsive picture element
- Add logo to all subdirectory README files in feature folders (01-10) and plugins
- Replace old markdown image syntax with HTML picture element for dark/light mode adaptation
- Logo automatically displays dark mode version when system prefers dark mode
- Maintain correct relative paths for all nesting levels (../, ../../, etc.)
- Update README.md with new logo syntax
All markdown files now use the new V2.0 starburst logo design with professional dark/light mode support.
Created a professional SVG logo for the project featuring:
- Modern gradient design with code brackets symbol
- Book/guide icon representing learning and documentation
- "Claude How To" branding with subtitle
- Decorative elements and professional color scheme
Added logo to all major documentation files:
- README.md
- INDEX.md
- QUICK_REFERENCE.md
- claude_concepts_guide.md
The logo provides consistent branding across the project and improves visual appeal on GitHub and other markdown viewers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added three new major feature categories with complete documentation and examples:
## New Features
### 07-hooks/
- Event-driven automation with 6 example hook scripts
- Pre/post tool hooks, session hooks, and git hooks
- Auto-formatting, security scanning, test automation
- Complete documentation with best practices
### 08-checkpoints/
- Conversation state snapshots and rewind capability
- Safe experimentation and approach comparison
- Real-world examples: DB migration, performance optimization, UI iteration
- Checkpoint management commands and workflows
### 09-advanced-features/
- Planning Mode: detailed implementation plans before coding
- Extended Thinking: deep reasoning for complex problems
- Background Tasks: long-running operations without blocking
- Permission Modes: unrestricted, confirm, read-only, custom
- Headless Mode: CI/CD integration and automation
- Session Management: multiple work sessions
- Interactive Features: keyboard shortcuts, command history
- 10+ configuration examples for different scenarios
## Documentation Updates
- README.md: Added sections for all new features with examples
- INDEX.md: Updated with new categories, file listings, and search keywords
- QUICK_REFERENCE.md: Added quick reference for new features
- claude_concepts_guide.md: Comprehensive guide sections for new concepts
## Statistics
- Total files: 90+ (up from 71)
- Categories: 9 (up from 6)
- New hook scripts: 6
- New documentation files: 10+
- Configuration examples: 10+ scenarios
All examples are production-ready and follow Claude Code best practices.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive examples for Claude Code features including slash commands, subagents, memory, MCP protocol, skills, and plugins with documentation and quick reference guides.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
