CalvinBackup/claude-howto
1
0
Fork 0
mirror of https://github.com/luongnv89/claude-howto.git synced 2026-08-08 00:08:36 +02:00
Code Issues Packages Projects Releases Wiki Activity
240 Commits 5 Branches 10 Tags
4f3fa85d7ed0f0f77f0d8bba3f0b40ff10b2063b
Commit Graph
21 Commits
Author SHA1 Message Date
Luong NGUYENandGitHub 4f3fa85d7e docs: follow-ups from the v2.1.220 accuracy review (#161) 
* 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.
 2026-08-06 07:58:46 +07:00
Luong NGUYENandGitHub 8143e37d1b perf(scripts): single-parse website build + CI caching (#144) 
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).
 2026-06-17 12:14:59 +02:00
Luong NGUYENandGitHub ae656f6fb8 docs: sync to Claude Code v2.1.176 (#141) 
* 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.
 2026-06-15 07:54:49 +02:00
Luong NGUYENandGitHub 3557d791f5 feat(scripts): add static website generator from markdown sources (#85) (#121) 
* 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)
 2026-05-15 08:55:29 +02:00
Luong NGUYENandGitHub 553a319934 feat(scripts): add markdown rendering validator (#119) (#120) 
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
 2026-05-11 23:49:39 +02:00
JiangChengandGitHub 1d1df9235b feat(i18n): Add Japanese (ja/) translation (#105) 
- Translate all 101 markdown files: P1 core, all 10 modules, examples,
  auxiliary docs (CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, CLAUDE.md, etc.),
  peripheral docs (.github/, docs/, resources/, scripts/)
- Translate comments and user-facing messages in 06-hooks/*.sh examples
- Copy 05-mcp/*.json examples (standard JSON, no comments)
- Update root README.md language switcher to include 日本語
- Add ja/TRANSLATION_NOTES.md (glossary + style guide)

All translations pass pre-commit quality gates (markdown-lint,
cross-references, mermaid-syntax, link-check, build-epub).
 2026-04-30 00:16:46 +02:00
Luong NGUYENandGitHub eff5bd226a test(scripts): cover repo-root boundary in check_cross_references (#95) 
* test(scripts): cover repo-root boundary in check_cross_references

Locks in the boundary behavior added in #91: links resolving outside
the repo root are silently skipped, in-repo broken links still error,
and valid in-repo links still pass.

* test(scripts): cover missing-README detection in numbered lesson dirs
 2026-04-25 00:33:21 +02:00
xiaolaiGitHubClaude Code
 		0bf754673a fix: constrain cross-reference resolution to repo root (#91) 
`(file_path.parent / link_path).resolve()` could silently follow a
crafted `../../outside/path` link that escapes the repository root.
Paths that resolve outside the repo root are now skipped rather than
checked for existence.

Co-authored-by: Claude Code <noreply@anthropic.com>
 2026-04-25 00:28:03 +02:00
xiaolaiGitHubClaude Code
 		6740288030 fix: pin requirements.txt to known-good versions (#90) 
All 6 packages were fully unpinned, allowing a compromised upstream
release to silently introduce malicious code on `pip install`. Pin to
current stable versions to ensure reproducible, auditable builds.

Co-authored-by: Claude Code <noreply@anthropic.com>
 2026-04-25 00:25:30 +02:00
Luong NGUYENandGitHub d17d5159e8 docs: sync to Claude Code v2.1.119 (docs host migration, /usage, hooks mcp_tool, native binary) (#94) 
- Migrate all docs.anthropic.com/en/docs/claude-code URLs to code.claude.com/docs/en
- Document /usage as canonical (v2.1.118); annotate /cost and /stats as shortcut aliases
- Update Opus 4.7: 1M context (v2.1.117 fix), xhigh default effort
- Note native-binary packaging (v2.1.113) and downloads.claude.ai host (v2.1.116)
- Hook events count normalized to 28 across all refs; add UserPromptExpansion, PostToolBatch
- Add mcp_tool as a fifth hook type (v2.1.118); duration_ms on PostToolUse (v2.1.119)
- Agent frontmatter mcpServers/permissionMode/--print tools honoring
- Glob/Grep -> bfs/ugrep footnote for native macOS/Linux builds
- Plugin marketplace enforcement (v2.1.117) + hostPattern/pathPattern (v2.1.119)
- --from-pr supports GitLab MR, Bitbucket PR, GitHub Enterprise (v2.1.119)
- Document 5 new env vars: DISABLE_UPDATES, CLAUDE_CODE_HIDE_CWD, CLAUDE_CODE_FORK_SUBAGENT, ENABLE_TOOL_SEARCH, OTEL_LOG_TOOL_DETAILS
- Deprecate includeCoAuthoredBy and voiceEnabled; add prUrlTemplate setting
- Add new features: /theme, /btw, claude plugin tag, claude install [version], sandbox.network.deniedDomains, auto mode "\$defaults", wslInheritsWindowsSettings, Vim visual modes, /doctor improvements, forked subagents, disableSkillShellExecution
- Refresh footers to Last Updated April 24, 2026 / Claude Code Version 2.1.119
 2026-04-24 08:20:55 +02:00
Thiên ToánandGitHub 90e9c30e93 feat(release): build and publish EPUB artifacts per language (#54) 
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).
 2026-04-07 09:14:06 +02:00
Luong NGUYENandGitHub 699fb39a46 ci: shift-left quality gates — add mypy to pre-commit, fix CI failures (#53) 
* 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.
 2026-04-07 00:51:44 +02:00
Luong NGUYENandGitHub e76bbe40f2 refactor(epub): replace Kroki HTTP dependency with local mmdc rendering (#10) (#52) 
* 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
 2026-04-06 23:44:59 +02:00
Luong NGUYENandGitHub 89e89d4aa3 feat(zh): add Chinese translations in zh/ directory 
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.
 2026-04-06 23:08:54 +02:00
Thiên ToánandGitHub 1b1670909d fix(epub): embed SVG images instead of replacing with placeholders (#46) 
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
 2026-04-06 22:04:44 +02:00
Thiên ToánandGitHub a70777e9bc Add Vietnamese (Tiếng Việt) Localization (#42) 
* feat(i18n): add Vietnamese localization infrastructure

Add comprehensive infrastructure for Vietnamese translation of the
claude-howto documentation:

Features:
- Parallel vi/ directory structure for Vietnamese content
- Modified build_epub.py with --lang flag for Vietnamese EPUB
- Vietnamese-specific pre-commit hooks for quality checks
- Translation support files (glossary, style guide, queue tracker)
- sync_translations.py script to detect outdated translations

Infrastructure:
- vi/ directory with all 10 module subdirectories
- TRANSLATION_NOTES.md: comprehensive glossary and style guide
- TRANSLATION_QUEUE.md: progress tracking for 66+ files
- vi/README.md: Vietnamese landing page

EPUB Build:
- Added --lang CLI flag (en/vi) to build_epub.py
- Language-specific metadata (title, subtitle)
- Automatic root path adjustment for vi/ directory
- Dynamic output filename (claude-howto-guide-vi.epub)

Quality Assurance:
- Vietnamese markdown linting
- Vietnamese cross-reference checking
- Vietnamese Mermaid syntax validation
- Vietnamese link checking
- Vietnamese EPUB build validation

Ready for translation work to begin.

* feat(vi): translate INDEX.md to Vietnamese

Complete Vietnamese translation of INDEX.md - the comprehensive
index of all example files in the repository.

Translation follows vi/TRANSLATION_NOTES.md guidelines:
- Technical terms kept per glossary (slash command → "lệnh slash")
- File paths and code blocks preserved in English
- Table structure and formatting maintained
- All 882 lines translated

Content includes:
- Complete file tree (10 modules, 100+ files)
- Feature coverage matrix
- Quick start guides by use case
- Learning path progression
- Search by keyword sections

Progress: 1/5 core documents completed

* feat(vi): translate CATALOG.md to Vietnamese

Complete Vietnamese translation of CATALOG.md - the quick reference
guide to all Claude Code features.

Translation follows vi/TRANSLATION_NOTES.md guidelines:
- Technical terms kept per glossary (slash command → "lệnh slash")
- All command names preserved (/help, /optimize, etc.)
- Code blocks, JSON examples, and bash commands unchanged
- All tables and formatting maintained
- 517 lines translated with complete feature coverage

Content includes:
- Summary statistics (99 built-in + 43 examples = 117 total)
- Complete built-in commands reference (55+ commands)
- Custom commands examples (8 commands)
- Permission modes (6 modes)
- Subagents (6 built-in + 10 custom)
- Skills (5 bundled + 4 custom)
- Plugins (3 complete plugins)
- MCP servers (1 built-in + 8 common servers)
- Hooks (25 events + 7 example hooks)
- Memory files (7 types)
- New features (March 2026) - 17 new features
- Installation priority guide
- Complete one-command installation

Progress: 2/5 core documents completed

* docs(vi): translate learning roadmap to Vietnamese

- Add complete Vietnamese translation of LEARNING-ROADMAP.md (747 lines)
- Include self-assessment quiz for level determination
- Translate three learning levels: Beginner, Intermediate, Advanced
- Translate all milestones (1A, 1B, 2A, 2B, 3A, 3B) with hands-on exercises
- Preserve Mermaid diagram for learning path visualization
- Maintain progress tracking checklists and learning tips

* docs(vi): translate quick reference guide to Vietnamese

- Add complete Vietnamese translation of QUICK_REFERENCE.md (507 lines)
- Include installation quick commands for all features
- Translate feature cheat sheet with usage examples
- Translate common use cases (code review, documentation, DevOps, etc.)
- Preserve all code snippets, commands, and file paths in English
- Maintain file locations reference diagram
- Include learning path and new features (March 2026) sections
- Keep tips & tricks, feature matrix, and checklist intact

* docs(vi): translate module 01 - slash commands to Vietnamese

- Add complete Vietnamese translation of 01-slash-commands/README.md (553 lines)
- Translate slash commands overview and architecture
- Include 55+ built-in commands reference table with Vietnamese descriptions
- Translate bundled skills section (5 skills)
- Document custom commands (now skills) migration path
- Include frontmatter reference, arguments, and dynamic context sections
- Preserve all command names, code examples, and Mermaid diagrams
- Translate 8 available commands in folder with usage examples
- Include installation, troubleshooting, and best practices sections

* docs(vi): update translation queue progress - Module 01 README done

- Mark 01-slash-commands/README.md as completed (2026-04-02)
- Update Module 01 progress: 1/9 files (11%)
- Update overall progress: 6/66 files (9%)
- Update Priority 2 progress: 1/31 files (3%)
- Add recent completion note to queue header

* docs(vi): translate slash command - commit to Vietnamese

- Translate commit.md slash command to Vietnamese
- Keep all git commands and technical syntax intact
- Translate instructions and descriptions
- Maintain conventional commits format documentation

* docs(vi): translate slash command - doc-refactor to Vietnamese

- Translate doc-refactor.md slash command to Vietnamese
- Keep all technical terms and file paths intact
- Translate documentation refactoring instructions
- Maintain structure and numbering

* docs(vi): translate slash command - generate-api-docs to Vietnamese

- Translate generate-api-docs.md slash command to Vietnamese
- Keep all technical terms and file paths intact
- Translate API documentation generation instructions
- Maintain output format specifications

* docs(vi): translate slash command - optimize to Vietnamese

- Translate optimize.md slash command to Vietnamese
- Keep all technical terms and code concepts intact
- Translate code optimization instructions
- Maintain issue priority and response format

* docs(vi): translate slash command - pr to Vietnamese

- Translate pr.md slash command to Vietnamese
- Keep all commands and technical syntax intact
- Translate PR preparation checklist instructions
- Maintain conventional commits format documentation

* docs(vi): translate slash command - push-all to Vietnamese

- Translate push-all.md slash command to Vietnamese (153 lines)
- Keep all git commands and technical syntax intact
- Translate comprehensive workflow with safety checks
- Maintain API key validation patterns and error handling
- Preserve when to use/avoid sections and alternatives

* docs(vi): translate slash command - setup-ci-cd to Vietnamese

- Translate setup-ci-cd.md slash command to Vietnamese
- Keep all tool names and technical terms intact
- Translate CI/CD pipeline implementation instructions
- Maintain pre-commit hooks and GitHub Actions sections

* docs(vi): translate slash command - unit-test-expand to Vietnamese

- Translate unit-test-expand.md slash command to Vietnamese
- Keep all framework names and technical terms intact
- Translate test coverage expansion instructions
- Maintain testing frameworks and scenario sections

* docs(vi): update translation queue - Module 01 complete (100%)

- Mark all 9 Module 01 files as completed (2026-04-02)
- Update Module 01 progress: 9/9 files (100%) ✅
- Update overall progress: 14/66 files (21%)
- Update Priority 2 progress: 9/31 files (29%)
- Update header with Module 01 completion milestone

Module 01: Slash Commands - All files translated:
✅ README.md (overview, built-in commands, skills)
✅ commit.md (git commit with context)
✅ doc-refactor.md (documentation restructuring)
✅ generate-api-docs.md (API documentation generator)
✅ optimize.md (code optimization analysis)
✅ pr.md (pull request preparation)
✅ push-all.md (stage, commit, push with safety)
✅ setup-ci-cd.md (CI/CD pipeline implementation)
✅ unit-test-expand.md (test coverage expansion)

* docs(vi): translate module 02 - memory guide to Vietnamese

- Add complete Vietnamese translation of 02-memory/README.md (1162 lines)
- Translate memory system overview and architecture
- Include quick reference for memory commands (/init, /memory, #)
- Document complete memory hierarchy (8 levels with precedence)
- Translate auto memory section with architecture diagrams
- Include practical examples (project, directory-specific, personal memory)
- Add best practices, installation instructions, and troubleshooting
- Preserve all code examples, file paths, and technical terms
- Maintain Mermaid diagrams and tables

* docs(vi): translate example project CLAUDE.md to Vietnamese

- Translate project-CLAUDE.md example memory file
- Keep all technical terms, commands, and code style intact
- Translate descriptions and explanations
- Maintain project configuration structure

* docs(vi): translate example personal CLAUDE.md to Vietnamese

- Translate personal-CLAUDE.md example memory file
- Keep all technical terms, tools, and preferences intact
- Translate descriptions and explanations
- Maintain personal preferences structure

* docs(vi): translate example directory-specific CLAUDE.md to Vietnamese

- Translate directory-api-CLAUDE.md example memory file
- Keep all technical terms, API standards, and code examples intact
- Translate descriptions and explanations
- Maintain API module standards structure

* docs(vi): update translation queue - Module 02 complete (100%)

- Mark all 4 Module 02 files as completed (2026-04-02)
- Update Module 02 progress: 4/4 files (100%) ✅
- Update overall progress: 18/66 files (27%)
- Update Priority 2 progress: 13/31 files (42%)
- Update header with Module 02 completion milestone

Module 02: Memory - All files translated:
✅ README.md (1162 lines - comprehensive memory guide)
✅ project-CLAUDE.md (example project memory)
✅ personal-CLAUDE.md (example personal preferences)
✅ directory-api-CLAUDE.md (example directory-specific rules)

* docs(vi): translate module 03 - skills guide to Vietnamese

- Add complete Vietnamese translation of 03-skills/README.md (805 lines)
- Translate Agent Skills overview and architecture
- Include progressive disclosure loading mechanism (3 levels)
- Document skill types, locations, and automatic discovery
- Translate skill creation process and SKILL.md format
- Include required and optional frontmatter fields
- Document skill content types (reference vs task)
- Translate controlling skill invocation and string substitutions
- Include dynamic context injection with shell commands
- Document running skills in subagents with context: fork
- Translate 6 practical examples with directory structures
- Add supporting files, management, and best practices sections
- Preserve all code examples, YAML frontmatter, and Mermaid diagrams
- Maintain tables, troubleshooting guides, and security considerations

* docs(vi): translate skill - blog-draft to Vietnamese

- Translate blog-draft/SKILL.md to Vietnamese (275 lines)
- Keep all workflow steps and technical structure intact
- Translate instructions and descriptions
- Maintain version tracking and file structure
- Preserve all markdown formatting and code examples

* docs(vi): translate skill - brand-voice to Vietnamese

- Translate brand-voice/SKILL.md to Vietnamese (73 lines)
- Keep brand identity, tone, and vocabulary intact
- Translate writing guidelines and examples
- Maintain preferred/avoided terms sections
- Preserve good/bad examples with explanations

* docs(vi): translate skill - claude-md to Vietnamese

- Translate claude-md/SKILL.md to Vietnamese (213 lines)
- Keep all golden rules and core principles intact
- Translate execution flow and content strategy
- Maintain WHAT/WHY/HOW structure
- Preserve quality constraints and validation checklist
- Keep anti-patterns and output format sections

* docs(vi): translate skill - code-review to Vietnamese

- Translate code-review/SKILL.md to Vietnamese (71 lines)
- Keep all review categories and template intact
- Translate security, performance, quality, maintainability sections
- Maintain review template structure
- Preserve version history

* docs(vi): translate skill - refactor to Vietnamese

- Translate refactor/SKILL.md to Vietnamese (427 lines)
- Keep all Martin Fowler refactoring methodology intact
- Translate 6-phase workflow with detailed steps
- Maintain core principles and safety rules
- Preserve code smell catalog and refactoring techniques
- Keep quick start example with before/after code
- Maintain version history and references sections

* docs(vi): update translation queue - Module 03 complete (100%)

- Mark all 6 Module 03 files as completed (2026-04-02)
- Update Module 03 progress: 6/6 files (100%) ✅
- Update overall progress: 24/66 files (36%)
- Update Priority 2 progress: 19/31 files (61%)
- Update header with Module 03 completion milestone

Module 03: Skills - All files translated:
✅ README.md (805 lines - comprehensive skills guide)
✅ blog-draft/SKILL.md (275 lines - blog post creation workflow)
✅ brand-voice/SKILL.md (73 lines - brand voice consistency)
✅ claude-md/SKILL.md (213 lines - CLAUDE.md best practices)
✅ code-review/SKILL.md (71 lines - comprehensive code review)
✅ refactor/SKILL.md (427 lines - Fowler refactoring methodology)

* docs(vi): translate Module 04 Subagents README

Complete Vietnamese translation of subagents reference guide:
- Configuration and built-in subagents (general-purpose, Plan, Explore, Bash, statusline-setup, Claude Code Guide)
- Agent management with /agents command
- Automatic delegation vs explicit invocation
- Resumable agents and chaining
- Persistent memory across agent sessions
- Background subagents for parallel work
- Worktree isolation for safe experimentation
- Agent Teams (experimental feature)
- Best practices and usage patterns

* docs(vi): complete Module 04 Subagents translation

Translate all 6 subagent example definitions:
- code-reviewer.md: Expert code review specialist
- debugger.md: Root cause analysis and debugging
- documentation-writer.md: Technical documentation creation
- implementation-agent.md: Full-stack feature implementation
- secure-reviewer.md: Security-focused code review
- test-engineer.md: Comprehensive test coverage

Update translation queue progress:
- Module 04: 7/7 files (100%) ✅
- Overall: 31/66 files (47%)
- Next: Module 05 (MCP)

* docs(vi): complete Module 05 MCP translation

Translate comprehensive MCP (Model Context Protocol) guide:
- Overview and architecture diagrams
- Installation methods (HTTP, Stdio, SSE, WebSocket)
- OAuth 2.0 authentication support
- MCP tool search and dynamic updates
- Elicitation and prompt slash commands
- Configuration management (local, project, user scopes)
- Practical examples (GitHub, Database, Filesystem, Slack MCPs)
- MCP vs Memory decision matrix
- Code execution approach for solving context bloat
- MCPorter runtime reference
- Security best practices and troubleshooting

Translate 4 MCP configuration JSON examples:
- filesystem-mcp.json: File operations
- github-mcp.json: GitHub integration
- database-mcp.json: SQL queries
- multi-mcp.json: Multiple servers configuration

Update translation queue progress:
- Module 05: 5/5 files (100%) ✅
- Overall: 36/66 files (55%)
- Next: Module 06 (Hooks)

* docs(vi): complete Module 06 Hooks translation

Translate comprehensive Hooks guide:
- Overview and architecture
- Configuration structure (user, project, local scopes)
- Four hook types: command, HTTP, prompt, agent
- 25 hook events with matcher patterns
- Component-scoped hooks and subagent frontmatter
- JSON input/output format and exit codes
- Environment variables and best practices
- Security considerations and debugging
- Installation instructions

Copy 9 hook example files (code, no translation needed):
- format-code.sh: Auto-format code after write/edit
- log-bash.sh: Bash command logging
- notify-team.sh: Team notifications
- pre-commit.sh: Pre-commit validation
- security-scan.sh: Security scanning
- validate-prompt.sh: Prompt validation
- context-tracker.py: Token usage tracking
- context-tracker-tiktoken.py: Accurate token counting

Update translation queue progress:
- Module 06: 9/9 files (100%) ✅
- Overall: 45/67 files (67%)
- Next: Module 07 (Plugins)

* docs(vi): complete Module 07 Plugins translation

Translate comprehensive Plugins guide:
- Overview and architecture diagrams
- Plugin loading process and lifecycle
- Plugin types (Official, Community, Organization, Personal)
- Plugin definition structure and manifest
- Plugin structure example with all directories
- LSP server configuration and examples
- Plugin options (v2.1.83+) with userConfig
- Persistent plugin data via CLAUDE_PLUGIN_DATA
- Inline plugins via settings (v2.1.80+)
- Standalone vs Plugin approach comparison
- Practical examples (PR Review, DevOps, Documentation plugins)
- Plugin marketplace and distribution
- Marketplace configuration and definition schema
- Plugin source types and distribution methods
- Plugin CLI commands and installation methods
- Plugin features comparison table
- Testing, hot-reload, and managed settings
- Plugin security restrictions
- Publishing workflow and best practices
- Complete troubleshooting guide

Copy all plugin subdirectories (code, no translation needed):
- devops-automation/: Deployment workflows, incident management
- documentation/: API docs, README generation, templates
- pr-review/: Pull request review automation

Update translation queue progress:
- Module 07: 10+/10+ files (100%) ✅
- Overall: 55+/67 files (82%)
- Next: Module 08-10 (Checkpoints, Advanced Features, CLI)

* docs(vi): complete Modules 08-10 translation

Module 08: Checkpoints and Rewind (2 files)
- Overview and architecture
- Access methods (keyboard shortcut, slash command)
- Five rewind options (restore code+conversation, conversation, code, summarize, cancel)
- Automatic checkpoints and retention policies
- Use cases and practical examples
- Integration with git and best practices

Module 09: Advanced Features (3 files)
- Planning Mode: Two-phase implementation approach
- Extended Thinking: Deep reasoning for complex problems
- Auto Mode: Background safety classifier
- Background Tasks, Scheduled Tasks
- Permission Modes (default, acceptEdits, plan, auto, dontAsk, bypassPermissions)
- Print Mode, Session Management
- Voice Dictation, Channels, Remote Control
- Web Sessions, Desktop App, Task List
- Git Worktrees, Sandboxing, Managed Settings

Module 10: CLI Reference (1 file)
- CLI commands reference
- Core flags and options
- Interactive vs Print Mode
- Model selection and configuration
- System prompt customization
- Tool & permission management
- Output formats and scripting

Update translation queue progress:
- Modules 08-10: 6/6 files (100%) ✅
- All Modules 01-10: 61+/61+ files (100%) ✅
- Overall: 61+/67 files (91%)
- Remaining: Supporting docs (6 files)

* docs(vi): complete supporting documentation translation

Translate all 5 supporting documents:
- CONTRIBUTING.md: Contribution guidelines
- SECURITY.md: Security policy and vulnerability reporting
- CODE_OF_CONDUCT.md: Community standards and harassment policy
- STYLE_GUIDE.md: Documentation formatting conventions
- CHANGELOG.md: Version history (v2.2.0, v2.1.1, v2.1.0, v2.0.0)

Update translation queue to 100% completion:
- All Modules 01-10: 61+ files (100%) ✅
- Supporting Docs: 5/5 files (100%) ✅
- Overall: 67+/67 files (100%) ✅
- Status: HOÀN THÀNH ✅

* fix(vi): fix mermaid syntax and broken cross-references in Vietnamese translation

Fix invalid `#` comment in mermaid block (use `%%` instead) and update
cross-reference script to support Unicode/Vietnamese diacritics in anchor
generation. Fix broken anchor links across vi/ documentation files.

* fix(vi): remove inline mermaid comment causing parse error

Inline %% comments on node definition lines are not supported by the
mermaid parser. The surrounding HTML comment already explains this is
an incorrect example.
 2026-04-06 21:34:18 +02:00
Luong NGUYENandGitHub 6d1e0ae4af refactor(ci): shift quality checks to pre-commit, CI as 2nd pass (#34) 
* 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.
 2026-04-02 02:20:45 +02:00
Luong NGUYEN 58e586f09b refactor: Add new V2.0 logo with dark/light mode support to all markdown files 
- 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.
 2026-01-09 10:36:58 +01:00
Luong NGUYEN c2130fc769 refactor: Move Python configuration and requirements files to scripts/ directory for better organization 2026-01-09 09:55:03 +01:00
Luong NGUYEN 540508f392 ci: Add DevOps quality assurance with pre-commit hooks and GitHub Actions 
- Add pre-commit hooks: Ruff lint/format, Bandit security scan, YAML/TOML validation
- Add GitHub Actions CI workflow: lint, security, test, and build jobs
- Configure Ruff and Bandit in pyproject.toml
- Add pytest test suite for build_epub.py (25 tests)
- Fix code issues: exception chaining, httpx timeout, formatting
- Add requirements.txt and requirements-dev.txt
 2025-12-10 23:49:52 +01:00
Willy Hardy 57ff23f9e0 feat: Add EPUB generation tool and workflow 
- Introduced a new script to build an EPUB from markdown files, enhancing documentation accessibility.
- Added a GitHub Actions workflow for automated EPUB builds on version tag pushes.
- Created the initial EPUB file 'claude-howto-guide.epub' for distribution.

This update streamlines the process of creating and releasing the Claude How-To guide in EPUB format.
 2025-12-09 12:07:40 -05:00