Coverage Snapshot
| Area | Coverage | Notes |
|---|---|---|
| Landing surface | Good | tremor-landing is now the dedicated front door instead of overloading manual pages |
| Getting started | Good | what-is-paperclip, quickstart, core-concepts, architecture cover the main entry path |
| Board operator workflows | Good | Most day-to-day operator tasks are documented |
| Agent development | Good | Heartbeat and skill guides are present |
| Deployment | Good | Local, Tailscale, Docker, secrets, and environment variables are covered |
| API reference | Good | Core control-plane endpoints plus runtime and operations endpoints are documented |
| Operating corpus | Good | Curated operating/* appendix now routes into the Tremor company corpus |
| Visual guidance | Good | Style guide and visual-reference pages now exist |
| Troubleshooting | Good | Deployment, ops, and recovery are now grouped into a dedicated operating route map |
| Product screenshots | Thin | The site still relies more on diagrams and tables than screenshots |
Major Gaps
- Quickstart still mixes end-user install and contributor setup without an explicit chooser.
- Some deeper raw Tremor corpus pages remain linked from curated appendices rather than surfaced directly in nav.
- Product screenshots are still sparse; the site leans on diagrams and tables.
- API reference coverage is much stronger, but some endpoint families remain overview-level rather than endpoint-by-endpoint.
- There is still room for more diagrams on auth, deploy topology, and runtime wakeup flow.
- The landing page is intentionally compact, so deeper company narrative still depends on linked appendix pages rather than a fully published narrative set.
Presentation Conventions
Use these defaults when writing or revising docs:- Lead with the user outcome in the first paragraph.
- Prefer short sections with one idea per section.
- Use tables for comparisons and configuration surfaces.
- Use cards when directing the reader to the next page.
- Use diagrams for flows and architecture, not for decoration.
- Keep icons or illustrations subtle and functional.
- Avoid long, nested lists unless the page is explicitly procedural.
- Favor plain markdown over custom layout components unless a callout materially improves comprehension.
- Keep landing-page framing and editorial language out of reference pages.
Visual Rules
The site should feel:- readable first
- split into two clear modes: editorial landing and quiet manual
- operational, not promotional, once the reader leaves the landing page
- lightweight enough that a page can be scanned in under a minute
- The landing page can carry a small amount of editorial framing and a short surface map.
- Knowledge-base and operating pages should lead with one table or one diagram, not a hero section.
- Use one or two cards for follow-on navigation, not as the main body layout.
- Optional callouts should be reserved for sharp warnings or environment split points.
What To Improve Next
- Add more “choose your path” framing on pages that mix user and contributor flows.
- Promote additional high-value Tremor corpus files from linked appendix sources into dedicated published reference pages when they prove repeatedly useful.
- Add one or two more topology diagrams for deploy and auth pages if those areas keep expanding.
- Audit nav labels periodically so new pages do not blur the landing/manual/operating split.
Current Standard
The dedicated style guide now exists. Keep using this working rule in addition to it:- if the reader is deciding, use a table
- if the reader is navigating, use a card
- if the reader is learning a process, use ordered steps
- if the reader is understanding a system, use one diagram before the prose
Related Pages
Quickstart
Start here if you want to get Paperclip running
Architecture
Read the control-plane and adapter model overview
Docs style guide
Read the canonical writing and presentation conventions