CLI cleanup: align docs, stdio behavior, cache UX, and shard output after v0.6.13

[jonathanpopham]

Supermodel CLI Issue Drafts

These are draft issue bodies based on local testing against supermodel 0.6.13.

1. mcp writes non-JSON banner to stdout before JSON-RPC

supermodel mcp currently writes a readiness banner to stdout before JSON-RPC messages:

supermodel mcp 0.6.13 - ready
{"jsonrpc":"2.0","id":1,"result":{...}}

Repro:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | supermodel mcp --repo .

Expected:

• stdout should contain only JSON-RPC protocol messages.
• Human-readable startup logs should go to stderr or be suppressed in stdio mode.

Also observed:

• initialize reports serverInfo.version: "0.1.0" while the binary is 0.6.13.
• tools/list exposes memory-graph tools not mentioned in CLI docs: upsert_memory_node, create_relation, search_memory_graph, retrieve_with_traversal, prune_stale_links, add_interlinked_context.

2. --three-file does not produce documented .deps and .impact files

README says supermodel analyze --three-file produces three files per source file:

• .calls
• .deps
• .impact

Local smoke test produced only:

main.calls.go

Repro:

supermodel clean .
supermodel analyze . --three-file --force
find . -maxdepth 2 -type f \( -name '*.calls.*' -o -name '*.deps.*' -o -name '*.impact.*' \)

Expected:

• Either produce the documented three files, including empty-but-structured .deps and .impact shards, or update docs to say only non-empty shard files are emitted.

3. Generated docs-output is included in later analyses

After running:

supermodel docs . --output ./docs-output --force
supermodel analyze . --three-file --force

The analyze command uploaded the generated static site as part of the repo:

50 files to upload
html 38
json 2
txt 2
xml 2
...

The original smoke repo had only go.mod, main.go, and README.md.

Expected:

• Either default docs output should be excluded from future analyses, or docs should strongly warn users to add the output dir to .supermodel.json/.gitignore.

4. Bare supermodel watch leaves shard files after Ctrl+C

Root help says:

Press Ctrl+C to stop and remove graph files.

Observed:

supermodel --dir /private/tmp/supermodel-cli-smoke
# Ctrl+C
find /private/tmp/supermodel-cli-smoke -maxdepth 2 -type f -name '*.graph.*'

Result:

/private/tmp/supermodel-cli-smoke/main.graph.go

Expected:

• Either Ctrl+C cleanup should remove generated graph files, or help text should not promise cleanup.

5. restore --local reports zero files/functions for a tiny Go repo

Repro repo:

go.mod
main.go
README.md

main.go defines main, greet, and unusedHelper.

Command:

supermodel restore --local --dir . --max-tokens 1000

Observed:

**Codebase:** 0 files · 0 functions

Expected:

• Local mode should at least count recognized source files by extension.
• If local mode cannot count functions, wording should avoid claiming 0 functions.

6. compact <file> appends stats directly to stdout source output

Command:

supermodel compact main.go

Observed output ends with compacted source immediately followed by stats:

func unusedHelper() string {
	return "unused"
}main.go: 187 -> 182 bytes  (2.7% reduction, ~47 -> ~46 tokens)

Expected:

• Compacted source on stdout should remain valid standalone source.
• Stats should go to stderr, or at least be separated by a newline and gated behind a flag.

7. Cache reuse/invalidation behavior is confusing across commands

Sequence:

supermodel analyze . --force
supermodel graph .
supermodel find greet
supermodel focus main.go

Observed:

• graph, find, and focus each displayed Uploading and analyzing repository... instead of visibly reusing the earlier analyze result.

Later, after docs output polluted an analysis and was removed:

supermodel --dir /private/tmp/supermodel-cli-smoke

Watch loaded an existing cache with the polluted 43-file result:

Loaded existing cache (62 nodes, 65 relationships)
43 files · 4 functions · 65 relationships

Expected:

• Cache behavior should be consistent and explainable.
• Commands that reuse cache should say so.
• Commands should not reuse stale cache after generated files are removed.

8. README command table still lists watch [path]

Actual command surface has no watch subcommand. The watch daemon is the bare supermodel command.

README currently says:

watch [path] | Generate graph files on startup, then keep them updated incrementally

Expected:

• Replace watch [path] with bare supermodel.
• Update old blog/sample copy that says supermodel watch.

[coderabbitai]

🔗 Related PRs

#55 - Show graph stats summary after watch generates initial files [merged]
#56 - Add supermodel share command [merged]
#60 - Make watch the default command [merged]
#109 - fix: rootCmd args parsed as directory path — breaks watch cache loading [merged]
#120 - feat: add --three-file flag to generate .calls/.deps/.impact shards [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[jonathanpopham]

Scoped cleanup plan for public CLI readiness

Narrowing this issue to the production-ready CLI path we want to stand behind in public docs and the explainer article.

In scope

• Replace supermodel watch / watch [path] references with the bare supermodel daemon command.
• Deprecate --three-file: remove it from docs/help recommendations and keep compatibility with a clear deprecation path.
• Make Ctrl-C cleanup behavior true for bare supermodel: generated .graph.* shard files should be removed on shutdown.
• Fix cache correctness and UX: avoid silently reusing stale cache after meaningful repo content changes, and clearly report cache vs upload behavior.
• Fix restore --local: count recognized source files correctly and avoid misleading 0 functions output when local mode cannot reliably count functions.
• Verify supermodel update end-to-end enough to know whether it actually updates correctly, and fix or document any gap.

Out of scope for this pass

• mcp cleanup. The MCP surface is still under product review.
• compact cleanup. Keep it out of the public CLI story for now.
• share behavior unless it blocks the article path.

Public bar

The happy path should be boring and true:

curl -fsSL https://supermodeltools.com/install | sh
cd repo
supermodel
supermodel skill >> AGENTS.md

After this cleanup, we should be able to explain the CLI around the stable file-mode workflow without caveats.