docs: CLI-first install flow + accuracy sweep (memory, tooling, API, error codes)#106
Merged
Conversation
…rst templates
Cross-referenced every guide against the agentsfleet CLI, the OpenAPI spec, the
Zig runtime, and the M94 fleet-bundle template catalogue (Pull Request #438),
then corrected the drift the review surfaced.
Install flow (skills -> CLI-first templates):
- quickstart: full rewrite. Drop the markdown-skill host onboarding and the
fabricated ~/.config/agentsfleet/samples/ path; lead with the CLI install
one-liner, then `agentsfleet install --template github-pr-reviewer` and
manual webhook registration (native install prints the URL, it does not
auto-register via gh).
- index / install / cli/install / templates / running: same skills->template
pivot; remove host-agent, `npx skills add`, `/agentsfleet-install-platform-ops`.
Correctness fixes (docs vs source):
- exit codes: real 1/2/3/4/5 map (auth/network/server/validation/config), was 0/1/2.
- error codes: drop fabricated UZ-MEM-001, UZ-TOOL-004, UZ-AGT-001/002 and the
retired UZ-WH-003; use the real UZ-AGT-008/011, UZ-MEM-002, UZ-EXEC-003.
- authoring: replace invented validator strings (RuntimeKeysOutsideBlock,
name_mismatch, ERR_AGENTSFLEET_INVALID_CONFIG, the "install rejected" block)
with real wire codes; network.allow is optional; drop the unenforced <=200-char rule.
- memory: remove the non-existent `workspace` category and `tags` field;
memory_recall is a `query` search, not a key lookup; storage is a separate
Postgres schema+role (not a separate database); entries read back as JSON.
- tools: 32 built-in tools (was "23"); `shell` + the full file toolset are real
and declarable (deny-by-default), correcting the "no free shell" claim.
- webhooks: success body is {status:"accepted",event_id}; a paused/killed fleet
returns 200 {"ignored":"fleet_paused"}, not 410.
- api: soften the unverifiable JSON Web Token (JWT) "~15 min" lifetime; use a
real error example (UZ-AGT-009); note the 409 current_state field.
Verified: `mintlify validate` and `mintlify broken-links` both pass.
Related follow-ups handed off (separate repos, not in this diff):
ui/agentsfleet.dev/dist/install.sh still installs the skill and must drop it to
match these docs; the website (ui/packages/website) still markets the skills flow.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
…nked search)
The architecture reference (docs/architecture/direction.md, runner_fleet.md
§Selection policy) is explicit that fleet memory is selected, not searched:
memory_recall returns the raw entries whose key matches a substring filter and
the model decides relevance — no scoring, no ranking, no vector search. The
recency/category pinning applies to hydration (selection), not to recall. The
prior wording ("recency-ranked search") overstated it; this matches the
canonical model so memory.mdx and the architecture docs agree.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…<fleet_id> placeholder in webhook gh api - fleets/tools.mdx: memory_list no longer advertises a tags filter (tags was removed from the memory model in this PR; memory.mdx already says category/recency). - quickstart.mdx: the gh api webhook-registration URL used a literal example fleet UUID; replaced with the <fleet_id> placeholder so a copy-paste does not silently register the hook to the wrong fleet. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…w-up) UZ-BUNDLE-003 (424 Fleet Bundle credentials missing) is a real registered code — error_registry.zig:127 / error_entries.zig:123 — and is already documented in api-reference/error-codes.mdx (Fleet Bundle section). greptile flagged it as possibly fabricated because error-codes.mdx is unchanged in this PR and so wasn't in its diff view. Link the inline mention to the reference page so the code is verifiable from the quickstart. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
Author
|
Re: the inline greptile flag on
greptile flagged it because |
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
Cross-referenced every guide against the
agentsfleetCommand-Line Interface (CLI), the OpenAPI spec, the Zig runtime, and the M94 fleet-bundle template catalogue (Pull Request #438), then corrected the drift the review surfaced. Two themes: pivot the install story off the markdown-skill onboarding to a CLI-first template-catalogue flow, and fix factual drift.Install flow: skills → CLI-first templates
~/.config/agentsfleet/samples/path; lead withcurl … | bash, thenagentsfleet install --template github-pr-reviewer+ manual webhook registration (native install prints the URL; it does not auto-register viagh).npx skills add,/agentsfleet-install-platform-ops.Correctness fixes (docs vs source)
1/2/3/4/5map (auth/network/server/validation/config), was0/1/2.UZ-MEM-001,UZ-TOOL-004,UZ-AGT-001/002and the retiredUZ-WH-003; use realUZ-AGT-008/011,UZ-MEM-002,UZ-EXEC-003.network.allowis optional; dropped the unenforced<=200-charrule; 23 → 32 tools.workspacecategory andtagsfield;memory_recall(query)is a search, not a key lookup; separate Postgres schema+role (not a separate DB); entries read back as JSON.shell+ the full file toolset documented (deny-by-default), correcting "no free shell".{status:"accepted",event_id}; a paused/killed fleet returns200 {"ignored":"fleet_paused"}, not 410.current_statefield.Verification
mintlify validate✅ ·mintlify broken-links✅ · gitleaks ✅Follow-ups (separate repos / PRs)
agentsfleet/docs/architecturememory + platform-ops sync — companion PR.agentsfleetui/agentsfleet.dev/dist/install.shstill installs the skill;ui/packages/websitestill markets it — handoffs written for both.memory_recall's tool description still advertises vector search though the deployed backend is recency-only; andshell/file tools are declarable (if "23" was an intended supported subset, the registry doesn't gate it).🤖 Generated with Claude Code
Greptile Summary
This PR rewrites the install story from a host-agent/markdown-skill flow to a CLI-first template catalogue flow, and sweeps 15 docs files for factual drift against the CLI, OpenAPI spec, and Zig runtime. The corrections are wide-ranging and generally well-sourced.
~/.config/agentsfleet/samples/path,npx skills add, and/agentsfleet-install-platform-opsslash command; replaces them withagentsfleet install --template <id>and manual webhook registration.workspacecategory andtagsfield, correctsmemory_recallsemantics, updates tool count to 32, fixes webhook success body.Confidence Score: 4/5
Safe to merge with two targeted fixes — one fabricated error code and one stale decision-tree row.
Two issues remain unresolved: UZ-BUNDLE-003 in quickstart.mdx was introduced by this PR and contradicts its stated goal of removing fabricated codes. The troubleshooting decision tree still maps every non-zero install exit to the wrong section. The rest of the accuracy sweep is well-executed.
quickstart.mdx (fabricated UZ-BUNDLE-003) and fleets/troubleshooting.mdx (stale decision-tree row).
Important Files Changed
Sequence Diagram
%%{init: {'theme': 'neutral'}}%% sequenceDiagram participant U as User participant CLI as agentsfleet CLI participant API as agentsfleet API participant GH as GitHub U->>CLI: "curl | bash" U->>CLI: agentsfleet login CLI->>API: browser device flow API-->>CLI: JWT / workspace selected U->>CLI: agentsfleet templates CLI->>API: GET /v1/fleets/bundles API-->>CLI: catalogue listing U->>CLI: agentsfleet credential add github CLI->>API: POST credentials API-->>CLI: stored U->>CLI: agentsfleet install --template github-pr-reviewer CLI->>API: POST fleets API-->>CLI: fleet_id + webhook URL U->>GH: Add webhook manually GH->>API: "POST /v1/webhooks/{fleet_id}/github" API-->>GH: 202 accepted API->>API: fleet run opens%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%% sequenceDiagram participant U as User participant CLI as agentsfleet CLI participant API as agentsfleet API participant GH as GitHub U->>CLI: "curl | bash" U->>CLI: agentsfleet login CLI->>API: browser device flow API-->>CLI: JWT / workspace selected U->>CLI: agentsfleet templates CLI->>API: GET /v1/fleets/bundles API-->>CLI: catalogue listing U->>CLI: agentsfleet credential add github CLI->>API: POST credentials API-->>CLI: stored U->>CLI: agentsfleet install --template github-pr-reviewer CLI->>API: POST fleets API-->>CLI: fleet_id + webhook URL U->>GH: Add webhook manually GH->>API: "POST /v1/webhooks/{fleet_id}/github" API-->>GH: 202 accepted API->>API: fleet run opensComments Outside Diff (1)
quickstart.mdx, line 799 (link)UZ-BUNDLE-003A core goal of this PR is removing fabricated error codes. However,
UZ-BUNDLE-003introduced here doesn't appear in any other changed file, and theUZ-BUNDLE-*domain isn't mentioned in the error-code registry docs or the PR's list of real codes (UZ-AGT-*,UZ-EXEC-*,UZ-MEM-*,UZ-WH-*,UZ-TOOL-*,UZ-VAULT-*). A credential-missing error at install time would more plausibly map toUZ-AGT-*orUZ-VAULT-*. If this is a real code, it should also appear in the error-codes reference page; if not, it should be removed or replaced.Prompt To Fix With AI
Reviews (4): Last reviewed commit: "docs: link UZ-BUNDLE-003 to its error-co..." | Re-trigger Greptile