Skip to main content

Aeon 7 docs — working rules for Claude Code

These rules apply to everything under docs/aeon-v7/ — the new Aeon 7 (web staff client) documentation. If you're editing a file in this folder, follow this guide. It exists so that pages written by different people (and different Claude sessions) stay consistent.

For the full project workflow and to claim a page, see the Aeon 7 Docs — Page Tracker in Notion. The short version is below.

Workflow (the non-negotiables)​

  • Branch: all work happens on aeon-7-docs. Never edit main, and never edit docs/aeon/ (that's Aeon 6 — a different, still-live version).
  • Claim before you edit. Before changing a page, mark its row in the Notion tracker In progress with your name. One page, one editor at a time.
  • Sync before you start and before you push. If a push is rejected, pull the latest aeon-7-docs and push again. If a real merge conflict appears in a doc, stop and ask a human — it means two people took the same page.
  • Small commits, push often.

What Aeon 7 is (so the writing is accurate)​

Aeon is request- and workflow-management software for special collections and archives. Aeon 7 is the new browser-based staff web client that replaces the Windows desktop client — same system, new interface. Write as if the desktop client is the old way; the web client is where staff now do everything.

The product name in prose is "Aeon 7 web staff client" (or just "Aeon 7"). Key surfaces to name correctly: the Command Center (the dashboard), the command palette (Ctrl+K / ⌘K global search), queues, requests, users, activities, appointments, and the reading room.

Frontmatter (required on every page)​

YAML frontmatter, with double-quoted values:

---
title: "Editing a Request"
sidebar_label: "Editing a Request"
description: "One sentence describing what the page covers and the Aeon 7 context."
sidebar_position: 3
---
  • title and sidebar_label are usually the same.
  • description is a single sentence used for SEO/previews.
  • sidebar_position orders the page within its folder. Index pages omit it.
  • The H1 (# Title) directly under the frontmatter should match title.

Page structure​

  1. H1 matching the title.
  2. A short lead paragraph (no heading) that says what the page is and frames the task — workflow-first.
  3. Often a brief numbered "normal path" of the happy-path steps, then prose sections expanding on it.
  4. ## / ### sections from there. Keep headings task-oriented ("Edit and save", "When you'll edit a request").

Voice and tone​

  • Second person, present tense, active voice. "You open the request and click Save." Confident and direct.
  • Workflow-first: lead with what the user is trying to do, then the mechanics.
  • Bold real UI labels and button names exactly as they appear on screen: Save, Generate Invoice, Detail tab.
  • Put keyboard shortcuts and code-like tokens in backticks: Ctrl+S, ⌘K, D, 12345.
  • Quote or italicize exact on-screen strings (toasts, dialog copy): "No changes to save."
  • Don't say Aeon "ships" / "ships with." Aeon isn't a boxed product. Use "includes," "comes with," or "has" — e.g., "Aeon includes five standard batch processes." (The request field Shipping Option is unrelated; leave it as-is.)

Admonitions​

Use Docusaurus admonitions (:::type Title … :::) the way the existing pages do — they carry a lot of the page's nuance:

  • :::tip — "when you'll use this", orientation, handy shortcuts.
  • :::info — permission notes and "this only appears when…" conditions.
  • :::note — secondary nuances and edge behavior.
  • :::warning — destructive actions, timeouts, things that can bite.
  • :::danger — reserved for the Editor-review callout (see below).

Don't overuse them; one or two per section at most.

  • Link to sibling pages with relative Markdown links: [Routing a Request](./routing-a-request.md).
  • If a target page doesn't exist yet, name it in plain text (not a link) rather than creating a dead link — onBrokenLinks is set to warn, but dead links should still be avoided. Turn it into a real link once the page lands.

Verification discipline (this is the important one)​

These docs are written against the actual Aeon 7 application and source, not from memory. Do not invent UI labels, behaviors, permission levels, toast text, or queue names.

  • State only what you can verify. If you're unsure, flag it for a subject-matter expert rather than guessing.
  • Every in-progress page ends with two things:
    1. A :::danger Editor review — remove this callout (and the HTML comment below it) before publishing block listing the claims an SME must confirm and the screenshots needed.
    2. An HTML comment <!-- GENERATION METADATA … --> recording the sources read, what was verified line-by-line, and anything corrected. This is what lets a future Claude session regenerate or fact-check the page.

Preserve both of these while a page is in progress. See any existing page (e.g. daily-work/requests/editing-a-request.md) for the exact format.

Screenshots​

Screenshots are never committed to this repo — they live in Azure Blob Storage (via the Screenshot Manager system) and the page only contains a link to the public URL. Do not add image files to static/.

The flow:

  1. The editor captures the screenshots a page needs (manually, from the live Aeon 7 app — we do not use Playwright) and drops the PNGs in the screenshots/ folder at the workspace root — i.e. ../screenshots/ from this repo, alongside AtlasDocs/ and AeonWebNext/.
  2. When placing them, upload each to Screenshot Manager under product aeon-7 and the category matching the page's leaf folder (daily-work/billing/ → billing, customization/designers/ → designers, getting-started/ → getting-started, and so on).
  3. Embed the returned urls.markdown at the right spot in the page, then clear the local PNG from ../screenshots/.

Full details — auth, the upload command, the complete category table, and how to refresh an existing shot without breaking links — are in _internal/screenshot-workflow.md. Read it before doing a screenshot pass.

Definition of Done​

A page is Done only when:

  • Content is complete and accurate for the Aeon 7 web client.
  • Frontmatter is intact (title, sidebar_label, description, and sidebar_position on non-index pages).
  • Internal links resolve and the page renders correctly on staging (docs-staging.atlas-sys.com).
  • The screenshots the page calls for have been added.
  • An SME has reviewed it, and the :::danger Editor review callout and the GENERATION METADATA comment have been removed.

A page that still has the Editor-review callout is In review, not Done.

Format​

  • Pages are CommonMark Markdown (.md) — the site is configured for markdown.format: 'md'. Keep stray <, {, and } out of prose, or escape them; don't rely on MDX/JSX features.
  • Use Markdown tables for reference grids (fields, shortcuts, meanings).