* 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.
Extend the release workflow to build separate EPUB artifacts for en, vi,
and zh in parallel via a matrix job, then publish all built files under
a single GitHub Release. Using fail-fast: false so a failure in one
language does not block releasing the others.
Also refactor build_epub.py to drive language-specific paths, filenames,
and titles from a mapping, and add zh support (title/subtitle + choice).
* fix(hooks): make hook scripts compatible with Windows Git Bash and use stdin JSON protocol
- Replace `grep -P` (Perl regex) with `sed` for JSON field extraction,
as Windows Git Bash does not support `grep -P`
- Replace positional arg (`$1`) with stdin JSON parsing to match the
actual Claude Code hook protocol (hooks receive data via stdin, not args)
- Fix JSON double-quote escaping in grep patterns that silently fails
on Windows Git Bash
- Remove python3 dependency for JSON parsing, making scripts portable
- Add Windows Git Bash to compatibility notes in script headers
Affected scripts: security-scan.sh, validate-prompt.sh, log-bash.sh, format-code.sh
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix(hooks): address review issues in Windows Git Bash compatibility scripts
- security-scan.sh: wrap output in hookSpecificOutput format required by
PostToolUse protocol; restore secret/token detection pattern that was
dropped; escape file path and issues for safe JSON construction
- validate-prompt.sh: extract "user_prompt" field first (Claude Code
UserPromptSubmit protocol), falling back to "prompt"
- log-bash.sh: document sed truncation limitation for commands with
double-quoted strings
- format-code.sh: fix misleading comment about updatedInput output
* fix(hooks): produce valid JSON from security-scan.sh
- Use \\n (JSON newline escape) when building ISSUES, not real newlines,
so the value passes safely through printf into the JSON string
- Remove the real-newline-to-\\n sed pass (no longer needed)
- Output is now verifiably valid JSON per python3 json.loads
* fix(hooks): fix grep -E POSIX compat and semgrep/trufflehog stdout mixing
- Replace \s with [[:space:]] in grep -E patterns (security-scan.sh lines
34,44): \s is a Perl extension, silently fails on macOS BSD grep and
BusyBox — password/secret detection was a no-op on macOS
- Suppress stdout of semgrep/trufflehog (>/dev/null) to prevent their
output mixing with hookSpecificOutput JSON, which would produce invalid
JSON and cause the additionalContext to fail parsing
- Fix format-code.sh hook comment: PreToolUse → PostToolUse (matches
README example and actual hook behavior)
---------
Co-authored-by: Bruce <binyuli1993@foxmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add performance-optimizer subagent and dependency-check hook
Agent-Logs-Url: https://github.com/khanhnkq/claude-howto/sessions/ef3fb01c-a9c0-466e-9ad2-f255f306add2
Co-authored-by: khanhnkq <180888435+khanhnkq@users.noreply.github.com>
* fix(hooks): use basename for manifest matching in dependency-check.sh
FILE=$1 receives an absolute path (e.g. /home/user/project/package.json).
The case statement and all [[ "$FILE" == ... ]] guards matched bare filenames,
so every invocation would hit the *) exit 0 branch and skip all vuln scans.
Extract BASENAME=$(basename "$FILE") and use it for all pattern matching.
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Luong NGUYEN <luongnv89@gmail.com>
The autoCheckpoint setting does not exist in Claude Code's settings
schema. Checkpointing is automatic and built-in — every user prompt
creates a checkpoint. Replace the incorrect config example with the
actual cleanupPeriodDays setting, which controls retention period.
Fixes#18
* feat: add missing pre-tool-check.sh hook to 06-hooks
The LEARNING-ROADMAP.md (Milestone 2A) referenced this file in an
exercise that copies it to ~/.claude/hooks/, but the file did not exist.
This caused confusion for learners following the guide.
The new pre-tool-check.sh is a PreToolUse hook for the Bash matcher that:
- Blocks unconditionally destructive commands (rm -rf /, dd, fork bomb, etc.)
- Warns on high-risk commands (rm -rf, git push --force, DROP TABLE, etc.)
- Reads tool input JSON from stdin (matching Claude Code hook protocol)
- Requires no external dependencies (pure bash + grep)
Fixes#32
* fix(hooks): correct exit code, remove set -e, use portable sed in pre-tool-check.sh
- Change `exit 1` to `exit 2` so Claude Code actually blocks the command
(exit 1 is treated as a non-blocking error; exit 2 is required to block)
- Remove `set -euo pipefail`: `set -e` caused the script to exit on the
first non-matching grep result, skipping all remaining pattern checks
- Replace non-portable `grep -o '"command"\s*:\s*"[^"]*"'` with
`sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p'`
which works on both macOS (BSD) and Linux without GNU grep extensions
Closes#32
---------
Co-authored-by: Luong NGUYEN <luongnv89@gmail.com>
* ci: shift-left quality gates — add mypy to pre-commit, fix CI failures
- Add mypy pre-commit hook (mirrors-mypy v1.13.0) so type checks run locally
- Add [tool.mypy] config to scripts/pyproject.toml with overrides for untyped libs (ebooklib, sync_translations)
- Add mypy>=1.8.0 to requirements-dev.txt
- Fix CI test.yml: remove continue-on-error: true from lint/security/type-check jobs (was silently swallowing failures)
- Fix CI bandit -c path: pyproject.toml → scripts/pyproject.toml
- Fix CI mypy command: use --config-file scripts/pyproject.toml
- Fix CI build-epub: add type-check to needs, fix if: success() → !failure() && !cancelled()
- Fix ruff errors in sync_translations.py (RUF013 implicit Optional, SIM102 nested if)
- Fix mypy errors: add list[str] annotations to errors vars in check_cross_references.py and check_links.py
* fix(ci): install mmdc in build-epub job and correct return type annotation
- Add npm install step for @mermaid-js/mermaid-cli before Build EPUB
to fix CI failure (mmdc not found error)
- Fix check_translation_status() return type from list[dict] to
tuple[list[dict], list[dict]] to match the actual return value
* fix(ci): pass --no-sandbox to Puppeteer in build-epub CI job
mmdc (Mermaid CLI) uses Puppeteer/Chromium which requires --no-sandbox
in the GitHub Actions sandboxed environment. Add --puppeteer-config flag
to build_epub.py that passes a Puppeteer JSON config file to mmdc via -p,
and use it in the CI workflow to inject the no-sandbox args.
* refactor(epub): replace Kroki HTTP dependency with local mmdc rendering (#10)
Remove httpx/tenacity dependencies and Kroki.io API calls from the EPUB
build pipeline. MermaidRenderer now invokes mmdc (mermaid-cli) as a local
subprocess, eliminating intermittent CI failures caused by network
unavailability. CI workflow installs @mermaid-js/mermaid-cli before build.
* fix(epub): add subprocess timeout and fix deduplication log count
- Add 60s timeout to mmdc subprocess.run to prevent hanging builds
when Chromium/Puppeteer stalls in headless CI environments
- Fix misleading log that printed unique/total as equal counts;
now logs "N unique diagrams (M total blocks)" explicitly
- Add test_render_all_timeout and strengthen deduplication assertion
Add Chinese (Simplified) translations for all documentation, organized
under a dedicated zh/ directory that mirrors the English folder structure.
Co-authored-by: tanqingkuang <tanqingkuang@users.noreply.github.com>
Translations originally contributed by @tanqingkuang in #45.
Restructured from *-CN.md suffix pattern into zh/ directory to prevent
the EPUB builder (scripts/build_epub.py collect_folder_files) from
picking up Chinese files via glob("*.md") inside module folders.
The Foliate EPUB reader blocks <object> elements (not <img>), so SVG
images can be served via <img> tags. Embed SVG files as EPUB resources,
unwrap <picture>/<source> wrappers, and skip external badge URLs.
Closes#44
- Replace `grep -P` (Perl regex) with `sed` for JSON field extraction,
as Windows Git Bash does not support `grep -P`
- Replace positional arg (`$1`) with stdin JSON parsing to match the
actual Claude Code hook protocol (hooks receive data via stdin, not args)
- Fix JSON double-quote escaping in grep patterns that silently fails
on Windows Git Bash
- Remove python3 dependency for JSON parsing, making scripts portable
- Add Windows Git Bash to compatibility notes in script headers
Affected scripts: security-scan.sh, validate-prompt.sh, log-bash.sh, format-code.sh
Co-authored-by: Bruce <binyuli1993@foxmail.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* refactor(ci): shift quality checks to pre-commit, CI as 2nd pass
- Remove ci.yml (lint, security, pytest were only for EPUB scripts)
- Move EPUB build to pre-commit local hook (runs on .md changes)
- Add check_cross_references.py, check_mermaid.py, check_links.py scripts
- Add markdown-lint, cross-references, mermaid-syntax, link-check as
pre-commit hooks — mirrors all 4 CI doc-check jobs locally
- Remove spell check job from docs-check.yml (breaks on translations)
- Refactor docs-check.yml to reuse scripts/ instead of inline Python
- Add .markdownlint.json config shared by pre-commit and CI
- Update CONTRIBUTING.md with required dependencies and hook table
* fix(ci): resolve all CI check failures in docs-check workflow
- fix(check_cross_references): skip code blocks and inline code spans
to avoid false positives from documentation examples; fix emoji
heading anchor generation (rstrip not strip); add blog-posts,
openspec, prompts, .agents to IGNORE_DIRS; ignore README.backup.md
- fix(check_links): strip trailing Markdown punctuation from captured
URLs; add wikipedia, api.github.com to SKIP_DOMAINS; add placeholder
URL patterns to SKIP_URL_PATTERNS; add .agents/.claude to IGNORE_DIRS
- fix(check_mermaid): add --no-sandbox puppeteer config support via
MERMAID_PUPPETEER_NO_SANDBOX env var for GitHub Actions Linux runners
- fix(docs-check.yml): pass MERMAID_PUPPETEER_NO_SANDBOX=true to mermaid job
- fix(content): repair broken anchors in README.md, 09-advanced-features;
fix #plugins -> #claude-code-plugins in claude_concepts_guide.md;
remove non-existent ./docs/performance.md placeholder links; fix
dependabot alerts URL in SECURITY_REPORTING.md; update auto-mode URL
in resources.md; use placeholder pattern for 07-plugins example URL
- remove README.backup.md (stale file)
* fix(check-scripts): fix strip_code_blocks regex and URL fragment handling
- fix regex in strip_code_blocks to avoid conflicting MULTILINE+DOTALL
flags that could fail to strip indented code fences; use DOTALL only
- strip URL fragments (#section) before dispatching link checks to avoid
false-positive 404s on valid URLs with anchor fragments
* fix(check-scripts): fix anchor stripping, cross-ref enforcement, and mermaid temp file cleanup
- heading_to_anchor: use .strip("-") instead of .rstrip("-") to also strip leading hyphens
produced by emoji-prefixed headings, preventing false-positive anchor errors
- check_cross_references: always exit with main()'s return code — filesystem checks
should block pre-commit unconditionally, not silently pass on errors
- check_mermaid: wrap file-processing loop in try/finally so the puppeteer config
temp file is cleaned up even if an unexpected exception (e.g. UnicodeDecodeError) occurs
- docs-check.yml: remove now-unused CROSS_REF_STRICT env var
* fix(scripts): fix anchor stripping and mermaid output path
- Replace .strip('-') with .rstrip('-') in heading_to_anchor() so leading
hyphens from emoji-prefixed headings are preserved, matching GitHub's
anchor generation behaviour.
- Use Path.with_suffix('.svg') in check_mermaid.py instead of
str.replace('.mmd', '.svg') to avoid replacing all occurrences of .mmd
in the full temp path.
- Replace broad wildcard allowlist with conservative defaults
- Add opt-in flags for edits, tests, git writes, packages, and gh writes
- Update README to match the new permission tiers
Remove the auto-adapt-mode PostToolUse hook (no more dynamic permission
learning). Replace with a standalone setup script that seeds ~67 safe
auto-mode-equivalent permission rules into settings.json in one shot.
Move the script to 09-advanced-features/ alongside the Auto Mode docs.
Adds a PostToolUse hook that automatically generalizes approved tool
invocations into reusable permission rules in settings.json. Seeds
auto-mode-equivalent baseline permissions on first run. Dangerous
commands (rm -rf, force-push, DROP TABLE, sudo, etc.) are never remembered.
Restructure README.md using the PAS (Problem-Agitate-Solution) copywriting
framework to better convert visitors into users. Adds badge row, benefit-driven
headline, problem/solution narrative, social proof, FAQ, and multiple CTAs.
All original technical content preserved in collapsible <details> sections.
Original README saved as README.backup.md.
Add MCPorter (github.com/steipete/mcporter) as a practical tool for
reducing MCP context bloat through selective tool exposure and typed
wrappers. Includes features table, installation, and usage examples.
- Replace docs.anthropic.com URLs with code.claude.com equivalents across all files
- Mark /review as deprecated with code-review plugin recommendation
- Fix "Sonnet 4.5" → "Sonnet 4.6" model name reference
- Update Task() → Agent() syntax in subagents documentation
- Remove undocumented /todos from slash commands table
- Add verification note about CLAUDE.local.md not in official docs
- Update dead URL github.com/anthropics/claude-code-skills to github.com/anthropics/skills
- Fix 10 relative tutorial links in self-assessment SKILL.md with correct ../../../ prefix
Mention /self-assessment and /lesson-quiz skills throughout both files so
learners discover them at every milestone, in progress tracking, and in a
dedicated "Test Your Knowledge" section.
Redesign LEARNING-ROADMAP.md with a self-assessment quiz that routes users
to Beginner/Intermediate/Advanced paths instead of a single linear track.
Add two project-local skills:
- self-assessment: comprehensive proficiency quiz (quick or deep mode)
covering 10 feature areas with per-topic scoring and personalized
learning paths
- lesson-quiz: per-lesson quiz with 100-question bank (10 per lesson)
for pre-test, progress check, or mastery verification
Update README.md learning path table with "Recommended For" column and
quiz link. Update .gitignore to track project skills.
Luong NGUYEN