docs(guides): add custom commands authoring guide

[Yumstezy]

Closes #111.

Adds a standalone guide at docs/guides/custom-commands.md for contributors who want to author a new /arckit.* command. The existing CONTRIBUTING.md has a ~12-line section on new commands; this guide expands on it with:

• The converter fan-out from arckit-claude/commands/ to the 5 other targets
• Frontmatter field reference (description, argument-hint, effort, handoffs, Claude-only fields)
• $ARGUMENTS placeholder rewriting table per target
• Template override pattern with ${CLAUDE_PLUGIN_ROOT} fallback
• Worked /arckit.sla example end-to-end
• Decision table for when to use a command vs skill vs agent vs hook
• Testing checklist

Happy to also add a docs/manifest.json entry if you want it indexed — noticed customize.md isn't listed there, so held off pending a steer on whether contributor-facing guides belong in the manifest alongside the user-facing ones.

[tractorjuice]

Review

Well-structured, accurate on the mechanics, and genuinely useful for contributors. A handful of factual nits and two indexing gaps to address before merge.

Strengths

• Converter claims match scripts/converter.py — $ARGUMENTS placeholder rewrites (line 249), template filename convention {name}-template.md (read_template_for_command(), line 334), ${CLAUDE_PLUGIN_ROOT} path prefix handling, the Gemini ~/.gemini/extensions/arckit/ sandbox workaround, and commands-standalone/ override for platforms lacking hooks — all verified correct.
• Frontmatter table is consistent with CLAUDE.md (effort, paths, keep-coding-instructions all correctly flagged as Claude-only).
• Worked /arckit.sla example is concrete enough to copy-paste from, and the commands/skills/agents/hooks decision table fills a real gap.

Merge blockers

1. Format count is wrong (intro vs. table)
Line 5: "fans out to six AI-assistant formats automatically" — but the table directly below lists seven rows (Claude source, Codex command, Codex skill, OpenCode, Gemini, Copilot, Paperclip). README and project memory both say 7 distribution formats. Either say "six other formats (plus the Claude Code source)" or switch to "seven distribution formats". Same inconsistency in the PR description ("converter fan-out from arckit-claude/commands/ to the 5 other targets").

2. CHANGELOG merge conflict — requires rebase
The branch is behind main (v4.9.0 shipped via #342 and #345 after this branch forked). The ## [Unreleased] insert conflicts. On rebase, keep the entry under [Unreleased] on the new base (per repo convention guide additions land there until the next bump).

3. Plugin mirror is missing
All guides are mirrored in both trees:

• docs/guides/<guide>.md
• arckit-claude/docs/guides/<guide>.md

PR only adds the first. Please also add arckit-claude/docs/guides/custom-commands.md (verified: all 111 guides currently exist in both trees).

4. Guide is not indexed in docs/README.md
grep custom-commands docs/README.md returns nothing. Add a link under an appropriate section — probably a new "Contributing" sub-section, or under Getting Started. This also answers your own open question about manifest.json: the primary index is docs/README.md; manifest.json is for the web viewer and is populated separately.

Accuracy nits

5. Template auto-pickup claim is overstated
Line around "The converter picks it up automatically by filename convention" — this is only fully true for Paperclip, which embeds template content into commands.json via read_template_for_command(). For other targets, the whole templates/ tree is copied verbatim to each extension's directory (copy_extension_files), and the command reads it at runtime via path prefix. Suggest:

"Paperclip embeds the template content directly into its generated commands.json; other targets copy the whole templates/ tree into each extension directory, and the command reads the file at runtime via the target's path prefix."

6. Target table has a small inconsistency
The first row is labelled "Claude Code (source)" but writes to arckit-claude/commands/ — which is the file you edit, not an output. Consider a "(edited by hand; all others generated)" note to avoid implying the converter writes it.

Minor nits

• Copilot placeholder is hard-coded: ${input:topic:Enter project name or topic} uses a literal topic: label regardless of what the command expects. Worth a parenthetical — authors can't currently customise it without editing scripts/converter.py.
• Branch name in the testing checklist says feature/<command-name>-command; repo's recent history mixes feat/ and docs/ prefixes — loose convention, don't prescribe one.

Summary

Merge blockers are items 1–4 (format count, rebase, plugin mirror, index). Items 5–6 and the minor nits are polish that could be folded in during rebase. Thanks for writing this — it's a real gap that needed filling.