Docs sync

docs-sync

Keep Argus public-facing documentation aligned with the actual codebase.

When to use

• Before tagging a release
• After adding/removing/renaming a CLI command
• After bumping argusVersion in gradle.properties
• After adding or modifying i18n keys in messages_en.properties
• User says: "sync docs", "update docs", "fix docs drift", "/docs-sync"

Authoritative sources (the truth)

Truth	Path
Project version	gradle.properties → argusVersion
CLI command set	argus-cli/src/main/java/io/argus/cli/command/*Command.java (one file per command, minus Command.java interface and any abstract base)
i18n keys (master)	argus-cli/src/main/resources/messages_en.properties
Locale parity	messages_{ko,ja,zh}.properties must contain every key from messages_en.properties
Java baseline	build.gradle.kts JavaLanguageVersion

Targets to update (the consumers)

Target	What to check
README.md	Version badges/numbers, "N commands" claim, install snippets, feature highlights
docs/README.md	"all N commands" copy
docs/cli-commands.md	"N Argus CLI commands" header, A–Z command index completeness
docs/getting-started.md	Version refs, JAR filename, command-count cell in compatibility table
docs/configuration.md	Flag names match code, default values match code
docs/architecture.md	Module list matches settings.gradle.kts
docs/usage.md	Spring Boot starter version
docs/kubernetes.md	Container image tag
docs/troubleshooting.md	Error messages match messages_en.properties
site/*.html	Version badge, command-count badge + prose + headings on every page (index.html, commands.html, comparison.html, dashboard.html, scenarios.html, integrations.html, reference.html), code samples

Procedure

Run all checks; only edit when a drift is confirmed. Never invent content.

1. Resolve the truth

ARGUS_VERSION="$(awk -F= '/^argusVersion=/{print $2}' gradle.properties)"

# Real command count: every *Command.java in the command/ dir, minus the Command interface and any abstract bases
CMD_COUNT=$(ls argus-cli/src/main/java/io/argus/cli/command/*Command.java \
  | grep -v -E '/(Command|AbstractCommand|BaseCommand|CommandGroup)\.java$' \
  | wc -l | tr -d ' ')

# i18n key sets
for L in en ko ja zh; do
  grep -E '^[a-zA-Z][^=]*=' "argus-cli/src/main/resources/messages_${L}.properties" \
    | cut -d= -f1 | sort > "/tmp/keys_${L}.txt"
done

Print a single TRUTH block to the user before doing any writes:

TRUTH
  version       = $ARGUS_VERSION
  commands      = $CMD_COUNT
  locale-keys   = en:N ko:N ja:N zh:N

2. Drift scan (read-only)

For each target file, search for any line that mentions a version or command count and compare to truth. Build a list of {file, line, was, should-be} entries. Don't touch files yet.

Useful greps:

# Version drift
grep -rEn 'v?[0-9]+\.[0-9]+\.[0-9]+' README.md docs/ site/*.html \
  | grep -v -E '(java|jdk|jvm|netty|micrometer|junit|spring|node|graalvm|grafana|prometheus|3\.[0-9]|11\+|17\+|21\+)' \
  | head -50

# Command-count drift (per-file listing)
grep -rnE '[0-9]{2}\+? ?(commands|Commands)' README.md docs/ site/*.html

# Command-count internal consistency (catches the trap where the SAME README
# says "67 commands" on line 14 and "66 diagnostic commands" on line 64 — listing
# alone doesn't fail; collapse all occurrences plus the runtime help banner to a
# unique-value set and fail if there's more than one).
COUNT_OCCURRENCES=$(grep -rhEo '[0-9]{2,3} (diagnostic )?commands?' \
    README.md docs/ site/*.html 2>/dev/null \
  | sed -E 's/ diagnostic / /' \
  | awk '{print $1}' \
  | sort -u)
HELP_COUNT=""
if command -v argus &>/dev/null; then
  HELP_COUNT=$(argus --help 2>&1 | sed -E "s/\x1b\[[0-9;]*m//g" \
    | grep -oE '[0-9]{2,3} commands' | head -1 | awk '{print $1}')
fi
echo "docs occurrences: $(echo "$COUNT_OCCURRENCES" | tr '\n' ' ')"
echo "argus --help    : ${HELP_COUNT:-(argus not on PATH)}"
echo "truth (source)  : $CMD_COUNT"
ALL=$(printf '%s\n%s\n%s\n' "$COUNT_OCCURRENCES" "$HELP_COUNT" "$CMD_COUNT" \
  | grep -E '^[0-9]+$' | sort -u)
if [ "$(echo "$ALL" | wc -l | tr -d ' ')" -gt 1 ]; then
  echo "DRIFT — multiple command counts in circulation: $(echo "$ALL" | tr '\n' ' ')"
else
  echo "OK — single command count everywhere: $ALL"
fi

# i18n parity
diff <(cat /tmp/keys_en.txt) <(cat /tmp/keys_ko.txt)
diff <(cat /tmp/keys_en.txt) <(cat /tmp/keys_ja.txt)
diff <(cat /tmp/keys_en.txt) <(cat /tmp/keys_zh.txt)

3. Command-list drift

Compare the A–Z index in docs/cli-commands.md against the actual *Command.java filenames. Report any command in source but not in docs (or vice versa). Do not invent docs entries — escalate to the user with a list and the natural category to add it under.

4. CLI example drift (best effort)

For any code block in README.md or site/*.html of the form argus <subcommand> ..., verify <subcommand> exists in the command set computed in step 1. Flag unknowns.

5. Fix policy

• Pure value swaps (version number, command count, badge text): edit directly.
• i18n parity gaps: add the missing key in each locale file. Translate using the file's existing tone; never use machine-generated stubs in production locales without an English fallback. Use printf %s placeholders, never MessageFormat {0} (project rule).
• Removed-command references in docs: ask the user before deleting prose about a command — they may want to keep a deprecation note instead.
• New commands missing from docs: ask the user which category (monitoring, memory-gc, threads, runtime-internals, profiling-tracing) and a one-line synopsis.

6. Verify

After edits:

./gradlew :argus-cli:test --quiet
# Re-run the diff in step 2; expect parity diffs to be empty

Output format

End with a structured report:

docs-sync report
================
Truth:    version=1.2.0  commands=66  i18n=529 keys × 4 locales
Checked:  N files
Drift fixed:
  - README.md:14            "65+ commands"  →  "66 commands"
  - site/index.html:970     "0.8.0"         →  "1.2.0"
  - messages_zh.properties  +4 keys (cmd.gcprofile.desc, ...)
Drift escalated:
  - docs/cli-commands.md does not list `argus newcmd` — please confirm category
Build verification: ./gradlew :argus-cli:test → exit 0

Project rules to honor

• Public-facing text in English (per project memory).
• i18n strings use printf %s, never MessageFormat {0}.
• All four locale files must stay in parity; do not skip a locale.
• Never commit to master directly — finish on a branch and propose a PR.
• Don't edit argusVersion in gradle.properties from this skill; that belongs to the release flow.

Out of scope

• External distribution surfaces (Helm chart, install.sh, Formula, docker-compose) → use release-sync.
• Translating English copy into KO/JA/ZH wholesale — only fill parity gaps.
• Generating new architecture diagrams or screenshots.