feat: Install UX, bug fixes, docs & doc consolidation#143
Merged
Conversation
Replace Claude-specific description with provider-neutral language referencing multiple agentic AI instances (Claude, Gemini and others). Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
Reviewed PLAN.md against 12 checks. All pass; two low-severity watch-items noted (Windows repro access for #115; CLAUDE.md/permissions constraint not restated in plan).
Add Task 2.3 to fix --help/-h guard in install command handler, and include #142 in the Issues Addressed list.
Independent review against 12 checks. All pass. Two low-severity NOTEs added for the doer: - Task 1.1 step 2 scope: Codex composePermissionConfig returns raw TOML string; 'route through smol-toml.stringify' may need the simpler alternative (base64 PowerShell) depending on where the Windows bug reproduces. - Task 2.2 pgrep/pkill pattern: risk register already names exact- match mitigation but task body still shows loose pattern; SEA installer would self-match. Tighten to pgrep -x or exclude self PID.
Verifies the new install --help guard task has clear done criteria, correct placement before VERIFY 2, appropriate cheap tier, and runtime ordering before any file writes / config reads / process detection. Three minor doer-side tightenings noted; one plan-hygiene suggestion to mirror the new acceptance checkbox into VERIFY FINAL.
… [1.1] Previously getProvider() silently fell back to Claude for any unknown llmProvider string (including corrupt registry entries or typos). PMs got Claude behavior while thinking their reviewer was running Codex. Now: undefined/null/empty still return Claude (legacy agents), but any non-empty unknown string throws a TypeError listing supported providers. Callers (execute-prompt, list-members, member-detail, compose-permissions, etc.) will surface the error instead of silently mis-routing. Also: add a regression test that parses the written Codex config.toml back with smol-toml.parse and asserts defaultModel is quoted properly, guarding against #115's reported 'model = \gpt-5.3-codex' output.
writeStatusline() returned early when agents.length === 0, leaving the
last-written icon lingering under Claude Code's input after remove_member.
Now on zero agents we overwrite statusline.txt with an empty line and
reset statusline-state.json to '{}' so a future registration starts
fresh rather than reviving stale 'busy' overrides.
Added tests/statusline.test.ts which drives the register -> busy ->
remove -> writeStatusline path against a real tmpfs sandbox (via
APRA_FLEET_DATA_DIR) and asserts the cleared file content.
Task 1.1 landed in d2571a3 (throw on unknown LLM provider + verify Codex TOML validity). Flagging done so progress.json matches reality for the reviewer.
ClaudeProvider.buildPromptCommand now appends ' -c' when a sessionId is
present, rather than the legacy '--resume \"<id>\"' syntax. Claude Code's
-c flag continues the most recent session and, when no session exists,
simply starts fresh — so first-call behavior is unchanged.
resumeFlag() mirrors the same: '-c' when sessionId given, '' otherwise.
buildResumeFlag helper stays exported for Gemini.
parseResponse + execute-prompt.ts's touchAgent(..., parsed.sessionId)
path is untouched, so session IDs are still captured for observability.
Updated tests/providers.test.ts Claude cases: session command must end
in ' -c' and contain neither '--resume' nor the raw session ID;
resumeFlag('ses-1') now returns '-c'.
- Bare `install` (no --skill flag) now defaults to skillMode='all' (fleet + PM skills installed), matching the intent of #139. - Added 'none' as a valid --skill value; --no-skill is a synonym. - Updated error message to list all four valid values. - Updated --help output in src/index.ts with new defaults table. - Added 4 matrix tests: bare install defaults, --skill none, --skill=none (equals form), --no-skill.
… [2.2] - isApraFleetRunning(): exact-name match via pgrep -x (not -f) on Linux/macOS to avoid self-match in SEA mode (NOTE 2); tasklist on Windows. - killApraFleet(): pkill -x (Linux/macOS), taskkill /F /IM (Windows). - runInstall guard fires only in SEA mode (skipped in dev); --force kills the running server, waits 500ms, then proceeds; appends "Restart Claude Code" to success message when --force was used. - Unknown --flags (typos) now error with a helpful message. - Exports _setSeaOverride / _setManifestOverride for test isolation. - 14 new tests in tests/install-force.test.ts covering Linux+Windows running/not-running/force paths, unknown-flag rejection, and helper units.
Add isApraFleetRunning() / killApraFleet() helpers using pgrep -x (exact name match per NOTE 2 — avoids self-match in SEA mode) on Linux/macOS and tasklist/taskkill on Windows. Guard fires only in SEA mode. Without --force: print error block with --force hint + platform kill hint, exit 1. With --force: kill server, wait 500ms, then proceed; success message appends "Restart Claude Code to reload the MCP server." line. Also: parse --force; reject unknown flags with a helpful error (typo-safety). Tests: 14 scenarios covering running/not-running, both platforms, kill commands, success messages, and unknown flag rejection.
Add early exit at the top of runInstall() before any file writes, config reads, or process detection. `apra-fleet install --help` and `-h` print install-specific usage text and exit 0 with no side effects. Added 2 tests verifying help exits 0 and produces no writeFileSync calls.
All three bug fixes verified against PLAN.md done-criteria and requirements.md acceptance items. Build clean (tsc), full suite green (640 passed / 4 skipped / 0 failed). Three non-blocking notes for housekeeping: vacuous-pass gap in one provider-factory test, stale commit hashes in progress.json post-rebase, standard pre-merge cleanup of sprint control files.
Add llms.txt at repo root (llmstxt.org spec) referencing the five canonical docs. Add scripts/gen-llms-full.mjs (no-deps Node script) that wraps each doc in <doc> XML and writes llms-full.txt. Commit the initial llms-full.txt so it's present before the first tag push. Update the CI release job to run gen-llms-full.mjs and include llms-full.txt in the post-release version-bump commit.
Covers dev-mode install command (npm run build && node dist/index.js install), file map for src/skills/hooks/CLAUDE.md, how to iterate on skill changes without a rebuild, the doer-reviewer loop convention, and sprint branch naming for agent-driven work.
Drop --skill from one-liner install commands (new default is all). Replace the old "What install does" bullet list with structured tables: - "What install writes" (paths for bin/hooks/scripts/skills) - "What install does NOT do" (no system changes, no daemons) - "The --skill flag" (all|fleet|pm|none|--no-skill options table) - "How to uninstall" (rm + claude mcp remove) Also update README.md one-liners and PM skill description to match.
…acked files Cleanup command was unconditionally rm-ing agent context files even when tracked by git. Apply fix from PR #105: only remove if not tracked. Restores AGENTS.md and CLAUDE.md deleted by the previous cleanup commit. Co-Authored-By: Claude Sonnet 4.6 <[email protected]>
kumaakh
force-pushed
the
feat/install-ux-and-docs
branch
from
2e878a4 to
ebfe0ca
Compare
… grep pattern, Task 1.2 note
…bs/apra-fleet into feat/install-ux-and-docs
…ing from readme.md Overlap map: - Missing in readme.md: manual install, what-install-writes table, what-install-does-NOT-do, --skill flag options table, uninstall, local/remote member registration detail, non-Claude provider registration, SSH key migration, run-prompt/command/send-files/check-status examples, multi-provider auth provisioning, CLI install, capabilities/limits, mix-and-match fleet example, GitHub App (Apra-Labs + custom + PAT), Bitbucket auth, Azure DevOps auth, PM commands table, troubleshooting section - AGENTS.md links to docs/user-guide.md (fix in 2.2) - CLAUDE.md is plan-execution agent context; Task 2.3 rewrites as thin wrapper
- scripts/gen-llms-full.mjs: path changed from docs/user-guide.md to readme.md, title updated from 'User Guide' to 'Readme' - llms.txt: User Guide entry replaced with Readme entry pointing to readme.md - llms-full.txt: regenerated (38798 bytes, 5 docs) — no docs/user-guide.md references
…d refs in script/llms.txt/llms-full.txt
…bs/apra-fleet into feat/install-ux-and-docs
…f truth Merged all 20 missing sections from user-guide.md into readme.md: - Manual install, what-install-writes table, what install does NOT do - --skill flag options table - Uninstall instructions (macOS/Linux + Windows) - Local vs remote member registration detail - Non-Claude provider registration (Gemini, Codex, Copilot) - SSH key migration steps - run-prompt, run-command, send-files, check-status usage examples - Multi-provider fleet: auth provisioning table, CLI install, capabilities/limits - Mix-and-match fleet example - Git auth: GitHub App (Apra-Labs + custom), GitHub PAT, Bitbucket, Azure DevOps - PM Skill section with full commands table - Troubleshooting section Long setup blocks wrapped in <details> collapsibles to keep readme scannable.
…f truth Merged all 20 missing sections from user-guide.md into readme.md: - Manual install, what-install-writes table, what install does NOT do - --skill flag options table - Uninstall instructions (macOS/Linux + Windows) - Local vs remote member registration detail - Non-Claude provider registration (Gemini, Codex, Copilot) - SSH key migration steps - run-prompt, run-command, send-files, check-status usage examples - Multi-provider fleet: auth provisioning table, CLI install, capabilities/limits - Mix-and-match fleet example - Git auth: GitHub App (Apra-Labs + custom), GitHub PAT, Bitbucket, Azure DevOps - PM Skill section with full commands table - Troubleshooting section Long setup blocks wrapped in <details> collapsibles to keep readme scannable.
- git rm docs/user-guide.md - Updated see-also comments in 8 docs files to reference ../readme.md - Updated docs/FAQ.md Related docs link from user-guide.md to ../readme.md - Updated AGENTS.md Links section: [User Guide](docs/user-guide.md) -> [Readme](readme.md) - Regenerated llms-full.txt (49567 bytes) — no user-guide refs remain in tracked source
Replaced plan-execution context with minimal Claude Code context: - Directive to read readme.md for full reference - Dev commands: npm install/build/test/build:binary - Branch naming, commit style, no-push-to-main convention No duplicated readme content. Under 30 lines.
Replaced 122-line tools reference with minimal agent context: - Directive to read readme.md for full reference - Dev commands: npm install/build/test/build:binary - Branch naming, commit style, no-push-to-main convention - Link to docs/architecture.md for internal structure No duplicated readme content. Under 30 lines.
kumaakh
changed the title
This was referenced Apr 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
readme.mdas single source of truthdocs/user-guide.md(349 lines, 20 missing sections) intoreadme.mdwith<details>collapsiblesdocs/user-guide.md; fixed all references across 8 doc filesscripts/gen-llms-full.mjsandllms.txtto usereadme.mdas sourceCLAUDE.md→ 18-line thin wrapper (was 122 lines)AGENTS.md→ 19-line thin wrapper (was 122 lines)Closes
#115, #108, #39, #96, #139, #142, #140, #136, #134
Test plan
npm run buildpassesnpm testpasses (748 tests)node scripts/gen-llms-full.mjsruns without errorreadme.mdcovers all content previously indocs/user-guide.mdCLAUDE.mdandAGENTS.mdunder 30 lines eachuser-guidereferences in tracked sourceReviews
c7d7e3d)🤖 Generated with Claude Code