> 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-full-hardening-kickoff.md).

# Claude Master 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-kickoff-prompt.md`
8. `docs/claude-shadow-layer-kickoff.md`

Then inspect the actual code before making any claims.

## Mission

Do a full product hardening pass on FleetOS so the codebase, UI, docs, API surface, and developer experience all tell the same truthful story, with no broken promises, no hidden features, and no unresolved architectural debt.

You are not here to do a partial cleanup. You are here to push FleetOS toward a 10/10 outcome on both:

1. code quality / architecture / correctness
2. UX / UI / copy / product / developer platform clarity

Do not stop at backend refactor only. Do not stop at docs only. Do not stop at visual polish only. Make the product coherent end to end.

***

## Non-negotiables

* Do not break current FleetOS core workflow behavior.
* Preserve supplier vs fleet role behavior.
* Keep changes incremental and strongly typed.
* Prefer smaller focused files over giant controller files.
* Do not leave docs claiming features that do not exist.
* Do not leave implemented features undiscoverable in UI/navigation.
* Do not let the shadow layer become a hard dependency for the core workflow.
* Do not silently swallow important errors.
* Do not rebuild from scratch.

***

## Highest-priority problems to solve

### 1. Core correctness and architectural integrity

You must verify and fix:

* unresolved imports
* missing files
* dead routes
* broken view/path mapping
* API/doc drift
* state-model contradictions
* hidden coupling between core workflow and shadow instrumentation

A likely example to check carefully:

* `services/requests/RequestWorkflowService.ts` imports `../shadow/ShadowInstrumentation`
* verify whether that file exists and whether the dependency is safe
* if it is missing or too tightly coupled, fix it first

### 2. Product truthfulness

The product currently has docs and developer surfaces, but they may over-promise relative to actual UI or implementation. You must align:

* homepage
* login / onboarding flow
* settings
* user docs
* developer docs
* API implementation
* terminology

### 3. Developer platform completeness

If API docs tell users to go to Settings → API Keys or Webhooks, that must visibly exist. If `/developers` exists, it must feel real. If the API exists, it must be discoverable.

***

## What success looks like

### Code 10/10

* clean build
* no missing imports
* no fake integrations
* no fragile coupling
* no state drift across UI/API/services/docs
* service boundaries are clean
* routing is stable
* settings and API surfaces line up with implementation

### Product 10/10

* homepage clearly explains FleetOS
* login/signup is obvious
* docs are easy to find
* developer docs are easy to find
* API keys are visibly manageable if documented
* webhooks are visibly manageable if documented
* terminology is consistent
* copy is sharp and credible
* product feels trustworthy and production-minded

***

## Required execution order

### Phase 1 — Audit reality before changing anything

Start by inspecting the real repo and produce a grounded assessment of:

* current routing structure
* current landing page and nav
* current login / onboarding flow
* current settings capabilities
* current docs pages
* current developer docs page
* current API implementation
* current shadow-layer implementation
* current state model in workflow services and UI adapters

Do not assume the docs are true. Verify them.

### Phase 2 — Fix critical correctness issues first

Before polishing anything, fix:

* missing or broken imports
* any `ShadowInstrumentation` dependency issue
* core workflow coupling to optional shadow layer
* obvious API/doc mismatch
* dead routes
* refresh/deep-link issues
* silent error swallowing in critical paths

### Phase 3 — Align the API, state model, and docs

Verify every documented endpoint against actual handlers. Verify every claimed settings/developer flow against actual UI. Resolve contradictions between:

* legacy `status`
* new `commercial_status`
* new `operational_status`
* UI status badges
* docs terminology
* webhook event names

If full split-status implementation is not ready, revise the docs and adapters honestly. If it is ready, finish the implementation properly.

### Phase 4 — Upgrade homepage, login, and discovery

Make FleetOS feel like a real product. You must improve:

* top navigation
* homepage hero and positioning
* product explanation
* developer platform discoverability
* login/signup clarity
* role-based CTA clarity
* footer/navigation consistency

### Phase 5 — Upgrade settings into a real control surface

If developer docs promise API keys and webhooks, build the visible UI. Split settings into a clear information architecture:

* Profile
* Operations / Shop
* Notifications
* Team
* API
* Webhooks
* Security

### Phase 6 — Rewrite docs to match reality

Tighten both user docs and developer docs. No fake promises. No aspirational language unless clearly labeled as upcoming. Make them actually useful.

### Phase 7 — Final consistency pass

Make terminology, navigation, status language, buttons, headings, and trust signals consistent across the whole app.

***

## Concrete task list

### A. Core correctness

1. Verify and fix `ShadowInstrumentation` import / implementation / coupling.
2. Replace silent `.catch(() => {})` on shadow instrumentation with structured warning/error logging.
3. Ensure core request workflow runs even if shadow layer is absent or disabled.
4. Audit `App.tsx` and `lib/navigation/resolveInitialView.ts` for route/view consistency.
5. Verify browser refresh and deep-link behavior for all major routes.
6. Remove dead or ambiguous view/path handling.

### B. API reality check

7. Verify all API handlers under `supabase/functions/api-v1` match `docs/openapi.yaml`.
8. Verify auth behavior, error behavior, and response shapes.
9. Verify API keys and webhook migrations are actually sufficient for the documented flow.
10. Ensure `/developers` docs are truthful.
11. Add any missing implementation needed for documented endpoints.

### C. State model alignment

12. Audit `services/requests/requestStateMachine.ts`, workflow services, UI mappings, and docs.
13. Decide and implement one truthful status model path:

* full split-status implementation, or
* compatibility layer with honest docs

14. Remove contradictory status language between API docs, dashboard UI, and services.
15. Keep a single source of truth for transitions, enums, and labels.

### D. Homepage and nav

16. Upgrade top nav on landing page:

* Product
* How it works
* Pricing
* Docs
* Developers
* Login
* Get Started

17. Add explicit developer CTA and section on homepage.
18. Rewrite hero and supporting copy so FleetOS is immediately understandable.
19. Make fleet / supplier / developer entry paths clear.
20. Tighten footer links and discovery paths.

### E. Login and onboarding

21. Make login obvious and distinct from signup.
22. Make returning-user magic-link flow feel intentional, not hidden.
23. Make fleet vs supplier onboarding paths clearer.
24. Ensure auth callback behavior is robust and predictable.

### F. Settings completeness

25. Add visible API key management UI if the docs say it exists.
26. Add visible webhook management UI if the docs say it exists.
27. Split settings into clearer sections or tabs.
28. Improve save flows, success/error states, and hierarchy.

### G. Docs hardening

29. Rewrite `DocsPage` so it matches actual product behavior.
30. Rewrite `ApiDocsPage` so every claim is verified.
31. Add links to OpenAPI spec if possible.
32. Add cross-links between homepage, docs, developer docs, and settings.
33. Add trust details: versioning, environment notes, support path, webhook verification, error model.

### H. Terminology cleanup

34. Standardize vocabulary across the product.
35. Decide canonical user-facing term: likely `Work Order`.
36. Keep legacy terms internal only where needed.
37. Remove drift between request/job/work order/RFQ wording.

### I. Dashboard / UI consistency

38. Verify the dashboard hook split is fully coherent.
39. Reduce remaining coupling and duplication.
40. Standardize headers, empty states, button styles, loading states, and error states across pages.
41. Make the whole app feel like one product, not stitched pages.

### J. Verification

42. Create and run a manual verification checklist covering:

* create work order
* quote
* approve / decline
* assign
* start
* add/update part
* ready for pickup
* request delivery
* complete
* cancel
* attachments
* webhook event emission
* API key flow
* docs / settings discoverability

43. Compare actual behavior against docs and fix any mismatch.

***

## Required output style while working

* Be concrete.
* Show exact files changed.
* Keep a running checklist.
* Make incremental commits.
* Call out assumptions explicitly.
* Call out risks before changing shared contracts.
* Do not drift into abstract discussion.
* Do not stop after a partial pass.

***

## First response format

Your first response must contain exactly these sections:

1. `Reality check`
2. `Broken or risky areas`
3. `Docs/implementation mismatches`
4. `Execution plan`
5. `First files I will change`

Then start work.

***

## Final bar

Do not declare success unless FleetOS feels coherent from all four entry points:

* operator landing experience
* supplier/fleet workflow experience
* settings/admin experience
* developer/integration experience

The code and the product must tell the same story.


---

# 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-full-hardening-kickoff.md?ask=<question>&goal=<user_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.