# Technical Guidance

This is a small Next.js application backed by Markdown, with canonical HTML pages, raw text routes, and an `llms.txt` manifest. Preserve that architecture.

## Editorial review comes first

Some changes look technical but are editorial. A new content type, a new frontmatter field, a new index page, a new public route, or a change to what `llms.txt` exposes are all editorial decisions before they are implementation ones.

For broad changes to content types, public routes, graph structure, or `llms.txt`, check only the
directly relevant guidance document. For small mechanical fixes, do not expand into editorial
review. The relevant documents are:

- `writing-style.md` for Journal structure and voice.
- `knowledge-graph-index.md` for the internal Knowledge Garden.

Implementation that runs ahead of editorial decision tends to lock in shape that later has to be unwound.

## Content model

Use simple Markdown with clear frontmatter for public content.

Expected fields for articles:

- `title`
- `date`
- Optional `status` (`published` or `draft`; omission means published)
- A non-empty `standfirst`
- `tags`
- Optional `location`
- Images belong in the Markdown body and established article image directory.

Expected fields for notes:

- `title`
- `date`
- Optional `status` (`published` or `draft`; omission means published)
- `tags`
- Optional `location`
- Do not add `standfirst`; standfirsts are for articles only.

Article standfirsts are not currently rendered on canonical article pages or journal indexes. They
supply page metadata, RSS descriptions, and the article descriptions in `llms.txt`.

Draft entries may live in their normal content directories while they are in progress. They should
use `status: "draft"` and remain hidden from canonical pages, raw routes, feeds, `llms.txt`, and the
sitemap until changed to `status: "published"` or the field is removed. Status is strict: any value
other than `draft`, `published`, or omission is a content error rather than an implicit publication.

The private Garden and Vault are separate sibling projects outside this repository. Private captures, research and original records do not belong in Lighthouse. Do not mount, symlink or import them into a build. Publication is an explicitly approved transfer of reviewed material into public content. The Garden output-tracing exclusion remains as a defensive safeguard against accidental reintroduction.

Journal connections live in `content/graph/journal.json`. Keep them separate from article and note
frontmatter. Concepts, entities and links are optional and curated; do not invent connections to
cover every piece. Every slug and related link must resolve to a published Journal entry.

Keep slugs stable and human-readable. Follow the existing filename patterns in `content/articles`,
and `content/notes`.

Static pages with raw mirrors live in `content/pages`. Their canonical HTML pages and raw routes must
both use `getStaticPage`; do not duplicate page prose inside route modules. Titles and descriptions
belong in the Markdown frontmatter so page metadata stays attached to the same source.

## Local development

Install dependencies:

```bash
npm install
```

Start the development server:

```bash
npm run dev
```

Build for production:

```bash
npm run build
```

Run TypeScript checks:

```bash
npm run typecheck
```

For Journal graph changes, check integrity and run the existing tests:

```bash
npm run graph:check
npm run graph:test
```

## Route principles

- Canonical routes are for people.
- Raw routes are for agents, archiving, quoting, and simple reading.
- Canonical and raw versions of a static page must render from the same Markdown source.
- Articles and notes share `/raw/journal/[slug]`; do not create a second raw article route.
- `llms.txt` points to the most useful raw routes and the interpretation rules a visiting model acts on, not to editorial standards.
- Public standards in `docs/` are written for people. Surface them through a human path such as the colophon, not through `llms.txt`. A writing or design standard is an instrument for producing the site, not something a visiting model needs to consume it.
- Do not let generated indexes drift from content metadata.

## Implementation principles

- Markup carries meaning. Reach for a `<section>` before a `<div>`, a link before a button. Style follows semantics.
- Inspect existing patterns before editing; do not invent a second content pipeline.
- Reuse existing components, CSS selectors, content loaders, and metadata helpers.
- Keep CSS close to existing global tokens and selectors.
- Avoid unnecessary dependencies or one-off rendering paths.
- Preserve accessible names, alt text, headings, nav labels, and current-page semantics.
- Preserve dark mode as a first-class reading mode.

## Privacy controls

Anything in public content directories is considered public. Agents that read the site can crawl raw routes systematically, which means there is no soft boundary that a human reader might naturally observe. If something should not be public to an agent, it should not be in a public content directory at all.

- Do not wire private notes or source files directly into the site.
- Public content lives in explicit public content directories, not in root private notes by accident.
- If generating from private context, create a new public-safe Markdown entry rather than exposing the source file.
- Strip confidential company details, financial figures, family specifics, and performance review text unless explicitly approved.
- Treat `llms.txt` as part of the public surface. Anything pointed to from it is public to every system that reads it.
- Content assets may expose only supported image files inside the established article and note
  image directories. Markdown, graph JSON, and Garden files must never be addressable through the
  asset route.

## Verification

- For small changes, use proportionate checks. Do not build, restart dev servers or use browser automation unless explicitly asked.
- Run `npm run build` after substantial code, route or content-structure changes, or when explicitly asked.
- When a browser check is explicitly requested, review layout, navigation, raw routes and dark mode.
- Mobile wrapping check for nav, footer, headings, metadata rows, and entry lists.
- Validate that `llms.txt` and raw indexes still point to existing routes.

## Technical taste

The implementation should mirror the site's editorial taste: small, legible, durable, and easy to reason about.

The architecture should survive neglect. It should be runnable a year from now without intervention, readable by a contributor who has never seen the codebase, and useful to systems — search engines, archives, agents — that did not exist when it was built. These are not separate concerns; they are the same concern at different scales.

The system should remain understandable without needing hidden operational knowledge. Prefer architectures that reveal their structure plainly through routes, files, naming, and content flow.