> 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-final-10of10-kickoff.md).

# Claude Final 10/10 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/claude-api-priority-hardening-kickoff.md`

Then inspect the actual code before making any claims.

## Mission

This is the final hardening pass to push FleetOS to **10/10 on both**:

1. code quality / architecture / correctness / security
2. product / UX / UI / copy / developer-platform credibility

Do not do another broad pass. Do not re-litigate the whole codebase. This pass is about fixing the remaining **critical finishing issues** that keep FleetOS from being truly production-grade.

***

## The three critical issues you must solve

### 1. Sensitive developer-platform data exposure

This is the highest-priority security issue.

Current risk:

* `api_keys`
* `webhook_subscriptions`
* `webhook_deliveries`

must not expose sensitive fields too broadly to client-side authenticated reads.

You must audit and fix the current self-service read path so that:

* raw API keys are never stored or readable after generation
* `key_hash` is not exposed in client-readable queries
* webhook secrets are never readable through general client table reads
* delivery data exposed to the client does not leak secrets or unsafe payloads unnecessarily

You may use:

* safer RLS
* safe views
* RPCs
* edge-function reads
* narrower client selects
* schema changes if needed

But the final result must be:

* self-service developer UX still works
* secrets and hashes are not broadly queryable
* the security story is credible

### 2. Shadow layer coupling and silent failure behavior

The shadow training layer must remain optional and non-fragile.

Current risk:

* `RequestWorkflowService.ts` directly imports and calls `ShadowInstrumentation`
* important shadow failures are swallowed with silent `.catch(() => {})`

You must fix this so that:

* the core workflow does not hard depend on the shadow layer
* the shadow layer is optional/additive
* failures are logged with structured warnings/errors
* the system can run cleanly even if shadow instrumentation is disabled

Use a clear boundary such as:

* observer interface
* no-op adapter
* feature-flagged instrumentation module
* injectable workflow instrumentation service

The final result must be:

* core workflow is safe
* shadow layer is additive
* no silent important failures remain

### 3. Final product/dev-platform polish to remove the last credibility gaps

The API and developer story are now much better, but still not 10/10.

You must finish the last-mile polish so that FleetOS feels like one coherent product.

Focus areas:

* landing-page nav completeness
* mobile discoverability for Docs / Developers / Login / Get Started
* settings information architecture (not just one long page)
* API docs excellence, not just credibility
* terminology consistency across product, docs, and API
* trustworthy environment / version / support cues for developers

You do not need to reinvent the UI. You need to remove the last signs of “good prototype” and make it feel production-minded.

***

## Explicit tasks

### A. Security and secrets — mandatory

1. Audit all current client-side reads against:
   * `api_keys`
   * `webhook_subscriptions`
   * `webhook_deliveries`
2. Identify which columns are currently exposed to authenticated users.
3. Ensure no client-readable path can expose:
   * `key_hash`
   * webhook `secret`
   * any equivalent sensitive internal credential material
4. Replace direct table reads with a safer pattern if needed.
5. Preserve the self-service UX for:
   * listing keys (safe metadata only)
   * generating keys (show once)
   * revoking keys
   * listing webhooks (safe metadata only)
   * creating webhooks (show secret once)
   * deleting webhooks
6. Verify that the docs and UI do not imply secrets are re-readable later.

### B. Shadow decoupling — mandatory

7. Remove direct hard dependency from `RequestWorkflowService.ts` to concrete shadow implementation if possible.
8. Introduce a clean instrumentation boundary.
9. Replace all important `.catch(() => {})` patterns with structured logging.
10. Ensure shadow instrumentation failures never break the operational workflow.
11. Ensure the system still builds and runs if shadow layer is disabled or no-op.

### C. Final developer-platform credibility — mandatory

12. Improve settings information architecture so API/Webhooks feel like a real developer/admin section.
13. Improve landing-page discovery on both desktop and mobile for:

* Docs
* Developers
* Login
* Get Started

14. Improve API docs with final trust signals such as:

* OpenAPI spec link if possible
* versioning / environment note
* clearer self-service key/webhook instructions
* clearer error/retry guidance

15. Standardize terminology so the product does not drift between request / job / work order unnecessarily.
16. Ensure homepage, settings, API docs, and implementation all tell the same truthful story.

***

## What you must NOT do

* Do not leave the security issue half-fixed.
* Do not keep secrets available through broad authenticated table reads.
* Do not leave shadow instrumentation hardwired into core workflow if a cleaner boundary is possible.
* Do not keep silent swallow patterns for important failures.
* Do not spend the pass on cosmetic tweaks while these issues remain.

***

## Acceptance criteria

You are not done unless you can explicitly show all of the following:

### Security

* client-readable developer tables no longer expose sensitive fields/hashes/secrets
* self-service developer UX still works
* docs accurately describe one-time secret visibility

### Core architecture

* shadow instrumentation is optional/additive
* core workflow no longer feels fragile because of shadow integration
* important shadow failures are logged, not silently swallowed

### Product / developer platform

* desktop and mobile discovery are both improved
* settings has a clearer developer/admin structure
* API docs feel finished and trustworthy
* terminology is consistent enough that an external developer is not confused

***

## Required output style while working

* Be concrete.
* Show exact files changed.
* Keep a running checklist.
* Make incremental commits.
* Call out the sensitive-field exposure analysis explicitly.
* Call out the shadow-decoupling design explicitly.
* Call out any remaining non-blocking polish items separately from the critical issues.

***

## First response format

Your first response must contain exactly these sections:

1. `Sensitive data exposure audit`
2. `Shadow coupling audit`
3. `Final credibility gaps`
4. `Execution plan`
5. `First files I will change`

Then start work.

***

## Final instruction

If you have to choose, prioritize:

1. security of developer-platform data
2. decoupling/shadow safety
3. final UX/dev-platform polish

Do not stop until those three are meaningfully complete.


---

# 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-final-10of10-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.