Grouped help, shell polish, export/import-palace, JSON output, aurora theme

[therahul-yo]

What this changes

A full polish pass over the CLI design plus two roadmap features, with matching tests and docs.

CLI design

• Grouped superton --help — commands are organized into guided panels (Start here / Ingest & capture / Ask & explore / Palace management / Model & system) with an examples footer, instead of one alphabetical dump. Added -V as a short version flag.
• New aurora theme — teal on black, northern-lights palette; fifth hand-tuned theme with its own ❖ prompt glyph, spinner, and rule character.
• NO_COLOR / SUPERTON_NO_COLOR — honors the no-color.org convention plus a scoped override for colorless-but-interactive terminals.

Interactive shell

• Typo guard — mistyped slash commands (/serach, /them) were silently forwarded to the model as chat; they now get a "did you mean /search?" nudge. Bare commands that need an argument (/add) print their usage line.
• Grouped /help cheatsheet — a themed four-group command map replacing the old one-line dump, mirroring the grouped --help panels.
• New commands — /list (recent drawers), /recent (recently added sources), /note <text> (quick capture), /why (toggle a retrieval trace under answers).
• Tab path completion for /add and /refresh arguments (directories chain with a trailing slash; dotfiles hidden unless asked for).

Features (from the project roadmap)

• superton export [-o file] / superton import-palace <file> — every drawer round-trips as JSON Lines for backup, sync, or migration. Content-addressed ids make re-import idempotent (imported 0 drawers · 4 already present).
• --json output on list, search, sources, stats, recent, and today — the Phase-3 "JSON output mode", landed early.

Fixes

• superton doctor misreported uv installs as pip: it resolved the interpreter symlink out of uv's tool venv before path-matching — the exact bug superton uninstall had already fixed. Doctor now checks sys.prefix + the raw executable.
• superton add <url> counted deduped chunks as newly ingested drawers.
• The ConfigError recovery hint pointed at ~/.superton/config.toml, which was never the config location.
• Removed shadowing duplicate ANSWER_CONTEXT_DRAWERS / ANSWER_DRAWER_CHARS constants in shell.py.
• Synced a stale uv.lock (project version + prompt-toolkit pin).

Validation

• uv run pytest — 262 passed, 1 skipped (21 new tests: export/import round trips incl. cross-home migration, malformed-line handling, every --json flag, typo suggestions, path completion, SUPERTON_NO_COLOR subprocess check, aurora registration)
• uv run ruff check . — clean
• uv run mypy superton — clean (strict core intact)
• uv build — wheel + sdist build
• Coverage 51.7% (gate is 45%)

README and CHANGELOG updated to match.

🤖 Generated with Claude Code

https://claude.ai/code/session_0145446GXbqRfpA4NF5Tn89E

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added JSON output for several commands, plus new export/import backup support.
  • Introduced a new aurora theme and improved theme selection in the app and shell.
  • Expanded interactive shell help, command hints, typo suggestions, /why, /note, /recent, /list, and path completion.

• Bug Fixes

  • Improved detection for environment/setup issues and clarified recovery guidance.
  • Fixed reporting for duplicate items during add/import flows.
  • Added better no-color handling for terminals that disable ANSI colors.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
superton	Ready	Preview, Comment	Jul 5, 2026 4:55am

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7410b8ec-e355-4b6e-806a-0bfe81e0b6e6

📥 Commits

Reviewing files that changed from the base of the PR and between 5749775 and d43fc7c.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (11)

• CHANGELOG.md
• README.md
• superton/cli.py
• superton/config.py
• superton/doctor.py
• superton/errors.py
• superton/shell.py
• superton/ui.py
• tests/test_cli.py
• tests/test_shell_helpers.py
• tests/test_ui_primitives.py

---

📝 Walkthrough

Walkthrough

This PR adds grouped CLI help panels with a -V flag, --json output across multiple read commands, export/import-palace backup commands, an aurora theme with NO_COLOR support, an init theme picker, doctor install-method detection fix, updated ConfigError hint, and shell REPL enhancements (help, completion, /note, /why, typo suggestions).

Changes

Superton CLI, shell, and theming updates

Layer / File(s)	Summary
Grouped CLI help panels and version flag superton/cli.py, tests/test_cli.py	Adds PANEL_* constants, reorganizes help/epilog text, adds -V short flag, and applies rich_help_panel grouping across most subcommands.
Init theme selection and ingest dedup tracking superton/cli.py	Adds --theme option and staged preflight plan to init; updates add/pull/demo to track and report deduped drawer inserts.
JSON output for read commands superton/cli.py, tests/test_cli.py	Adds --json support and a shared _drawer_dict serializer to list, recent, today, search, sources, stats, and doctor.
Palace export/import backup commands superton/cli.py, tests/test_cli.py	Adds export (JSONL output) and import-palace (JSONL ingestion with dedup counting and malformed-line skipping).
Uninstall and install-method detection superton/cli.py, superton/doctor.py	Strengthens uninstall with install-method detection and orphan cleanup sweeps; fixes _detect_install_method to avoid symlink-resolution misdetection.
Aurora theme, NO_COLOR, and config/error updates superton/ui.py, superton/config.py, superton/errors.py, tests/test_ui_primitives.py	Adds aurora theme, NO_COLOR/SUPERTON_NO_COLOR handling, expanded config theme whitelist, and an updated ConfigError recovery hint.
Shell REPL help, completion, note/why commands superton/shell.py, tests/test_shell_helpers.py	Adds command metadata (COMMAND_GROUPS, KNOWN_COMMANDS, COMMAND_USAGE), grouped /help, path completion for /add//refresh, /note, /why, typo suggestions, and show_why retrieval trace in _answer.
Documentation and changelog updates README.md, CHANGELOG.md	Documents new commands, themes, JSON flags, and env vars in README; adds Added/Fixed entries to CHANGELOG.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant REPL
  participant SuggestCommand
  participant Answer

  User->>REPL: types /lst (typo)
  REPL->>REPL: check KNOWN_COMMANDS
  REPL->>SuggestCommand: _suggest_command(head)
  SuggestCommand-->>REPL: closest match "/list"
  REPL-->>User: warn and suggest "/list"
  User->>REPL: types plain question
  REPL->>Answer: _answer(..., show_why=show_why)
  Answer-->>User: search hit cards + streamed answer

Loading

sequenceDiagram
  participant User
  participant CLI
  participant Palace
  participant JSONLFile

  User->>CLI: superton export -o palace.jsonl
  CLI->>Palace: fetch drawers
  Palace-->>CLI: drawer records
  CLI->>JSONLFile: write JSON lines
  User->>CLI: superton import-palace palace.jsonl
  CLI->>JSONLFile: read lines
  CLI->>CLI: parse and skip malformed lines
  CLI->>Palace: add drawer (dedup by content)
  Palace-->>CLI: added/deduped counts
  CLI-->>User: import summary

Loading

Possibly related PRs

• therahul-yo/Superton#2: Shares theme/config and shell _answer/retrieval-trace changes with this PR's aurora theme and show_why toggle.
• therahul-yo/Superton#11: Modifies the same init --theme flow and /help command restructuring in superton/shell.py.
• therahul-yo/Superton#14: Touches the same add/pull ingest code paths this PR updates for deduped drawer reporting.

Poem

A rabbit hopped through JSON trees,
Exported drawers with such ease,
Aurora glows in violet light,
No more color when told "not tonight,"
Typos caught before they land —
Hop hop, this palace feels so grand! 🐇✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}