> For the complete documentation index, see [llms.txt](https://t420.gitbook.io/t420/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://t420.gitbook.io/t420/claude-api-priority-hardening-kickoff.md). # Claude API-Priority Hardening Prompt Paste this into a fresh Claude Code terminal session at the FleetOS repo root. *** You are working in the `ZBO19/FleetOS` repository. Read these files first, in this order: 1. `docs/agent.md` 2. `docs/production-plan.md` 3. `docs/api-mcp-spec.md` 4. `docs/openapi.yaml` 5. `docs/shadow-training-layer.md` 6. `docs/shadow-training-schema-plan.md` 7. `docs/claude-full-hardening-kickoff.md` Then inspect the actual code before making any claims. ## Mission Do a full API-priority hardening pass on FleetOS. Your top job is to make FleetOS feel like a **real product with a real developer platform**, not a UI with backend fragments and not docs with missing product surfaces. This means you must harden all of the following together: * API correctness * API discoverability * developer settings/UI * homepage and nav discovery * docs truthfulness * core workflow correctness * shadow-layer safety Do not treat the API as a side quest. The API and developer story are a primary product surface. *** ## Critical instruction: API is priority #1 If you ignore the API, you are failing the task. You must explicitly verify and improve: 1. the actual API handlers 2. the OpenAPI spec alignment 3. the API docs page 4. the developer discoverability from homepage/nav/footer 5. the API key management story 6. the webhook management story 7. the settings/admin UI for developer controls 8. the truthfulness of all API/developer claims You are not allowed to leave FleetOS in a state where: * `/developers` looks good but the underlying platform feels incomplete * docs mention API keys/webhooks but the product has no credible path for them * the API exists but is hard to discover from the homepage * the API docs present a clean model while the code still contradicts it *** ## Non-negotiables * Do not break current FleetOS core workflow behavior. * Preserve supplier vs fleet role behavior. * Keep changes incremental and strongly typed. * Do not leave docs claiming features that do not exist. * Do not leave the API as a half-hidden feature. * Do not let the shadow layer become a hard dependency for the core workflow. * Do not silently swallow important errors. * Do not stop after backend work only. *** ## What “done” means You are not done until all of the following are true: ### A. API reality * Every documented endpoint maps to a real handler. * Auth behavior is real and explained truthfully. * Error behavior is real and explained truthfully. * Webhook behavior is real and explained truthfully. * The status model shown to developers is actually supported or honestly caveated. ### B. Developer experience * A visitor can find the API from the homepage/nav/footer. * `/developers` feels like a real developer surface. * There is a credible API key management path. * There is a credible webhook management path. * Settings/admin UI reflects the developer story. ### C. Product coherence * Homepage, docs, settings, API docs, and implementation tell the same story. * No fake claims remain. * No key feature is hidden behind footer archaeology. ### D. Core integrity * No missing imports. * No fragile shadow coupling. * No silent catch-and-ignore patterns for important failures. * Routing is stable. * Deep-linking and refresh work. *** ## Highest-priority problems you must solve ### 1. API-platform incompleteness The API is strategically important to FleetOS. Treat these as blocking gaps: * no visible API key management UI if docs or product imply it * no visible webhook management UI if docs or product imply it * weak developer discovery from landing/nav * docs that are more mature than the actual product surface ### 2. API/doc/code drift You must compare and align: * `docs/openapi.yaml` * `components/fleetos/pages/ApiDocsPage.tsx` * `supabase/functions/api-v1/**` * any API-related tables/migrations * any settings/admin UI related to API keys and webhooks ### 3. Shadow instrumentation safety The shadow layer now exists, but the main workflow must not become fragile because of it. Verify and improve: * direct coupling from `RequestWorkflowService.ts` * error handling around shadow calls * optionality / isolation of the shadow layer *** ## Required execution order ### Phase 1 — API reality audit first Before polishing anything else, inspect and report on: * all API handlers * OpenAPI spec * API docs page * API key tables and flows * webhook tables and flows * settings/admin UI related to API * homepage/nav discoverability of developer features Your first implementation work must be driven by the API audit. ### Phase 2 — Fix blocking API/platform gaps Fix these before visual polish: * missing or incomplete API handler coverage * docs/implementation mismatches * no-UI or weak-UI API key story * no-UI or weak-UI webhook story * weak homepage/nav discoverability of developer platform ### Phase 3 — Fix core correctness gaps Then fix: * shadow coupling * silent error swallowing * routing inconsistencies * status-model contradictions * dead or confusing product paths ### Phase 4 — Finish product coherence Then improve: * landing page nav and copy * login / onboarding clarity * settings hierarchy * docs truthfulness and cross-linking * terminology consistency *** ## Explicit task list ### API and developer platform — mandatory 1. Audit every handler under `supabase/functions/api-v1/**` against `docs/openapi.yaml`. 2. Build a matrix of endpoint → handler → docs coverage → status. 3. Fix any documented endpoint that is missing, broken, or mismatched. 4. Fix any handler that exists but is undocumented. 5. Audit `ApiDocsPage.tsx` line by line against the actual implementation. 6. Remove or caveat any API/docs claim that is not yet true. 7. Add a clearly visible developer path from homepage/nav, not just footer. 8. Add a stronger developer CTA on the landing experience. 9. Add or improve API/developer entry points in settings. 10. If self-serve API keys are not truly implemented, either: * implement them, or * make the product and docs explicitly managed-service for now. 11. If self-serve webhooks are not truly implemented, either: * implement them, or * make the product and docs explicitly managed-service for now. 12. Ensure the API story is visible and believable for an external developer. ### Core and architecture — mandatory 13. Fix the `RequestWorkflowService` ↔ shadow instrumentation coupling so the shadow layer is optional/additive. 14. Replace all silent `.catch(() => {})` patterns on important paths with structured logging. 15. Audit route/view handling and fix refresh/deep-link issues. 16. Verify the dashboard/service refactor still builds and behaves cleanly. 17. Resolve status-model contradictions between legacy `status` and API/docs split-status claims. ### Product/UI/copy — mandatory 18. Upgrade top navigation so docs/developers are discoverable without scrolling to the footer. 19. Tighten homepage copy so FleetOS clearly presents both: * operational coordination product * API/developer platform 20. Make login/signup clearer and more intentional. 21. Improve settings hierarchy so product settings and developer/admin settings are clearly separated. 22. Ensure user docs, developer docs, homepage, and settings all cross-link properly. 23. Standardize terminology across UI, docs, and API. *** ## Acceptance criteria You are not allowed to say the task is complete unless you can explicitly show: 1. **API surface audit completed** * endpoint matrix created * mismatches fixed or honestly documented 2. **Developer discoverability fixed** * homepage/nav/footer point to developer path clearly 3. **Developer control-plane story fixed** * API key and webhook story is either truly self-serve or clearly managed-service * no ambiguous in-between state 4. **Core workflow safety fixed** * shadow layer optional/additive * no silent failures 5. **Docs truthfulness fixed** * no claims ahead of implementation 6. **Product coherence fixed** * homepage, settings, docs, API docs, and implementation align *** ## Required output style while working * Be concrete. * Show exact files changed. * Keep a running checklist. * Make incremental commits. * Call out assumptions explicitly. * Call out API mismatches explicitly. * Call out product-surface gaps explicitly. * Do not give vague progress summaries. * Do not stop after a partial pass. *** ## First response format Your first response must contain exactly these sections: 1. `API reality audit` 2. `Developer platform gaps` 3. `Core correctness risks` 4. `Execution plan` 5. `First files I will change` Then start work. *** ## Final instruction If forced to choose between polishing visuals and fixing the API/developer platform story, fix the API/developer platform story first. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://t420.gitbook.io/t420/claude-api-priority-hardening-kickoff.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.