Work on this site

The site you are reading is one small repository. Fixing a typo, correcting a guide and adding a tool to the catalog are all changes to a text file in it. This guide shows where everything is.

What the site is made of#

The site is built with Next.js, TypeScript and Tailwind CSS, and exported as static files. It has no server, no API routes and no database. The guides are written in MDX, which is Markdown that can also hold a few components.

You do not need to know any of those to fix a sentence. You need a text editor and a GitHub account.

Make a small fix without installing anything#

For a typo or a wording change:

1. Open the file on GitHub. Each guide ends with a Source of this page link that goes straight to it.
2. Click the pencil icon to edit.
3. Make the change and choose Propose changes.

GitHub creates a copy of the repository under your account and opens a pull request from it.

Set it up on your machine#

You need Node.js 20 or newer, and git.

git clone https://github.com/ClearedStack/clearedstack.com.git
cd clearedstack.com
npm install
npm run dev

Open http://localhost:3000. The page reloads as you save files.

Find your way around#

src/
  app/              pages: home, /tools, /guides, /platform, /about, plus icons and metadata
  components/       header, footer, logo, the catalog list, the page lists and the diagrams
  data/
    catalog.ts      the areas and tools shown on the site
    registry.json   the naming registry: one entry per platform component
    platform.ts     typed access to the registry
    site.ts         name, addresses, contact email, short disclaimer
  guides/           one .mdx file per guide, served under /guides/
  platform/         one .mdx file per platform page, served under /platform/
  tools/            the detailed specification of a tool, shown on its page at /tools/<slug>/
  lib/docs.ts       reads both folders, puts the pages in order and lists the sections
scripts/            builds the search index before each build
public/brand/       logo files
Containerfile       builds the site and serves it with nginx
docker/             the nginx configuration used by the image
k8s/                Kubernetes manifests

Three places hold nearly everything a contributor changes: src/data/catalog.ts for the tools, the folder src/guides for the guides, and the folder src/platform for the pages about how the project is built and run.

Add or change a catalog entry#

Open src/data/catalog.ts and add an entry to the tools list:

{
  slug: "wrap-rate-calculator",
  name: "Wrap Rate Calculator",
  summary: "Build a fully burdened labor rate from base pay, fringe, overhead, G&A and fee.",
  category: "pricing",
  status: "planned",
},

The home page, the catalog page and every count on them are generated from this list. There is nothing else to update.

Each tool also gets a page of its own at /tools/<slug>/. These optional fields fill it in:

The build stops with a message if a tool names a guide or a heading that does not exist.

A tool can also have a detailed specification: the inputs, the logic, the checks and the worked examples it is tested against. Put it in src/tools/<slug>.mdx, named after the tool’s slug, and it is shown on the tool’s page under the summary.

Add a guide#

Create a file in src/guides. The file name becomes the address: src/guides/my-guide.mdx is served at /guides/my-guide/. Start the file with its details, then write in Markdown:

export const meta = {
  title: "The title of the guide",
  summary: "One sentence shown in the list and under the title.",
  group: "field",
  order: 9,
};

The first paragraph says what the guide covers and who it is for.

## A heading

Text, lists, tables and code blocks.

The guides page, the table of contents, the reading time, the previous and next links, the search index and the sitemap all pick the file up on the next build.

Add a platform page#

Pages about how the project chooses, builds and runs things live in src/platform and are served under /platform/. They are written exactly like guides, with two differences:

A page named after a component in the naming registry (src/data/registry.json) is that component’s specification, and shows its registry entry above the text. The registry is the only place a component’s name is written down: to rename one, change it there and rename the page to match.

Set status to what is true today, not what is planned. A page that describes something not yet running is a design, however complete the description. Change the label when the thing it describes changes.

Diagram components#

All guides and site pages have access to five static, accessible diagram components built with plain semantic HTML and CSS (no client-side JavaScript or external CDNs). In MDX files, they are available globally without an import:

• <Flow caption="..." steps={[{ label: "...", detail: "..." }]} />: Ordered sequential flows or pipelines. Optional props: direction="across" | "down", loop="Label for return", highlight={0}.
• <Branch caption="..." question="..." options={[{ when: "...", then: "...", detail: "..." }]} />: Decision points and branching choices.
• <Layers caption="..." layers={[{ label: "...", detail: "..." }]} />: Top-to-bottom stacks for rate build-ups and isolation boundaries.
• <Lanes caption="..." lanes={["Owner", "AI agent"]} steps={[{ lane: 1, label: "...", detail: "..." }]} />: Swimlanes mapping steps to responsible actors.
• <States caption="..." states={[{ id: "x", label: "...", to: [{ id: "y", when: "..." }] }]} />: State machine cards showing transitions and terminal states.

Here is an example in MDX:

<Flow
  caption="How a contribution is reviewed"
  direction="down"
  steps={[
    { tag: "1", label: "Open pull request", detail: "Contributor submits branch with tests and source citations." },
    { tag: "2", label: "Audit sources", detail: "Human maintainer verifies claims against official publications." },
    { tag: "3", label: "Merge", detail: "Shipped with git attribution trailers." },
  ]}
/>

AI-assisted work and commit trailers#

ClearedStack uses AI coding assistants to help draft code, documentation and tests, under human direction and review.

• Accountability: The human repository maintainer sets priorities, reviews every line of code, verifies every calculation against primary sources, and merges pull requests.
• Commit trailers: Commits drafted or iterated with AI assistance should include a Git trailer identifying the tool:

  Add Prior Art engine documentation
  
  Assisted-by: Claude Code
  Assisted-by: Antigravity
  

• No AI in the tools: Tools in the catalog contain no AI models and make no network calls. AI is used only to help write them. See How AI is used to build this project.

Human maintainerAI assistant

1. 1 · Human maintainerSets direction & architectureDefines the job, constraints, and underlying official regulations.
2. 2 · AI assistantDrafts code & documentationProposes TypeScript logic, static diagrams, tests, and MDX guides.
3. 3 · Human maintainerVerifies against official textChecks formulas and citations line by line against eCFR or NIST.
4. 4 · Human maintainerReviews and mergesTests client-side CSP boundaries and signs commit with trailers.

What you can use in a guide#

Ordinary Markdown works: headings, bold text, links, numbered and bulleted lists, code blocks and tables.

• Second-level headings (##) become the table of contents and get a link of their own. Keep them short, and do not repeat one within a guide.
• Links to other pages on the site start with a slash, such as /guides/your-data/.
• Tables use pipes. Put ---: under a column to align numbers to the right.
• Callouts set a short passage apart:

<Callout kind="warning" title="Optional title">
One or two sentences the reader should not miss.
</Callout>

The kind can be note, check or warning. Use them sparingly. A page with five callouts has none.

Two characters need care in MDX, because it reads them as code: a left curly brace and a less-than sign. Write “less than” in words, or put the text in backticks.

How the guides are written#

The guides are for people who are good at their own work and new to this subject. A few habits keep them readable:

• Plain words. If a simpler word says the same thing, use it.
• Define a term the first time it appears, and add it to the glossary.
• One idea per paragraph. Short sentences.
• Say what to do, then why.
• Cite the rule. Name the regulation and the part, so the reader can check.
• Date anything that changes. Do not print a rate or a threshold without saying when it was current, or better, tell the reader where to look it up.
• Made-up examples only. No real companies, contracts or rates.

Guides that describe regulations should set reviewed and end with a “Sources” section.

Check your change#

Before you open a pull request, run:

npm run lint
npm run typecheck
npm run build

All three should finish without errors. The build is the important one: it compiles every page, and it stops with a message if a page’s details are missing or a tool points at a guide that does not exist.

Then look at the result. Run npm run dev, open the pages you changed, and check them at a narrow window width and in dark mode. The site follows the system color setting.

Send it#

1. Create a branch for your change.
2. Commit with a message that says what changed and why.
3. Push the branch to your copy of the repository and open a pull request.

Small fixes can go straight to a pull request. For anything larger, open an issue first so the work is not wasted.

Rules for every change#

• Nothing loads from another server. No external fonts, scripts, images, embeds or analytics. The content security policy would block them, and the project’s promise depends on it.
• No tracking of any kind. No cookies, counters or forms that send data.
• No classified information, CUI, export-controlled data or real contract data, in code, examples, screenshots, issues or commit messages.
• Public sources only. “Public” means officially released.
• By contributing you agree that your work is released under the MIT License.