Editing these docs

This site is a folder of Markdown files rendered by Astro Starlight. Anyone who can edit a text file can edit the docs. The repository is stratl-docs, deployed to docs.stratl.ai on every push to main.

Where things are

stratl-docs/
  src/content/docs/        every page, one file each, in folders that become sidebar groups
    start/ executives/ compliance/ portal/ build/ reference/ contributing/
  src/components/          Paths, Pipeline, Claim, Persona, and the PageTitle override
  src/styles/custom.css    the theme: tokens, fonts, sidebar, cards. Change colours here only
  astro.config.mjs         site settings and the sidebar group order
  openapi/stratl.json      the API description the reference pages are generated from

Add or change a page

1. Create or open a .md file in the right folder. Use .mdx only if the page needs a component (Steps, Tabs, Persona, Claim).

2. Fill the frontmatter:

   ---
   title: Retention and legal holds
   description: One sentence a search result would show.
   audience: [compliance, operators]   # everyone | executives | compliance | operators | engineers
   minutes: 7                          # optional reading time, shown under the title
   sidebar:
     order: 4                          # position inside the folder's group
   ---

   The audience chips and the reading time render automatically. The sidebar label is the title; set sidebar.label to shorten it.

3. Write in Markdown. Asides: :::note, :::tip, :::caution blocks, or the Aside component in MDX. Tables for anything with more than two columns of facts. Fenced code with a language.

4. Preview: pnpm dev and open http://localhost:4322. The page appears in its group at once; the search index rebuilds on pnpm build.

5. Check and publish: pnpm build runs the Astro checks and fails on a broken component or a bad frontmatter value. Commit and push; Vercel deploys.

Writing rules

These docs are read by people under pressure, in four different jobs. The rules that keep them readable:

• Say who the page is for in the frontmatter, and write for them. An executive page has no code; an engineering page has no reassurance.
• Lead with the answer. The first paragraph says what the page tells you.
• One idea per sentence. Short does not mean clipped.
• Name things the way the product names them. The vocabulary in the glossary is fixed; the portal, the API, the record and the verifier use the same words.
• Never claim what the code does not do. No “explainable AI”, “reasoning”, “compliance guaranteed”, “immutable forever” or “impossible to tamper”. Records capture observable facts; storage refuses deletes; verifiers check. When something is not built, say not yet and link the security page.
• Numbers go in tables. Rules, limits and defaults are easier to check in a table than in prose.
• Link the other paths. A compliance page links the engineering page for the same topic, and the reverse.

Keep the four sources of truth in step

When the product changes, four things describe it: the early-access page on the website, the security page, this site, and the API’s own description. Change them in the same week. The security page and its cross-linked claims page must agree row for row.

Packs and other content that lives in code

Some text comes from the backend repository, not from here: framework packs and their gap sentences (api/packs/*.yaml), notice rights text and deadlines (api/app/notices/drafter.py), the verifier’s check names (cli/internal/srf/verify.go), and every setting (api/app/config.py). When those change, update the matching docs page: frameworks, notices, the verifier, configuration.

The API reference

The pages under Reference → API reference are generated from openapi/stratl.json. To refresh them after an API change, in the backend repository:

make openapi     # exports the service's description into ../stratl-docs/openapi/stratl.json

Then commit the file here. Endpoint descriptions come from the docstrings in the API code, so write them for a reader.

Components

Component	Use
<Persona who="compliance">	A short “if you are X, read this” callout inside a page
<Claim title status docs code>	One security-page row with its backing; only on the claims page
<Steps>	Numbered procedures; every step starts with a verb
<Tabs> / <TabItem>	Language or platform alternatives
<Paths>, <Pipeline>	Landing page only

Style

The theme lives in one file, src/styles/custom.css: fonts (Figtree for text, JetBrains Mono for code, Geist for the wordmark), the light and dark palettes matching the website and the portal, and the sidebar, card and aside styles. Change tokens there and nowhere else.