# Agent Instructions

This repository is the **user-facing documentation** for Data Controller for SAS®, published at [docs.datacontroller.io](https://docs.datacontroller.io). It is a [MkDocs](https://www.mkdocs.org/) site using the Material theme.

## Related repositories

Data Controller spans three sibling repositories (usually checked out side by side under the same parent directory):

- **`dc`** - the product source (Angular client + SAS backend). The behaviour documented here is implemented there. Deep technical notes live in `dc/.agent/docs/`.
- **`docs.datacontroller.io`** (this repo) - the user-facing product documentation.
- **`datacontroller.io`** - the marketing site, blog and feed (Gatsby).

When documenting a feature, the source of truth for behaviour is `dc`. When a doc page describes internals, prefer linking to the user-facing concept rather than duplicating implementation detail.

## Structure

- Pages are Markdown files in `docs/`.
- The navigation tree, site config, theme, plugins and redirects are all defined in `mkdocs.yml`. **A new page is not published until it is added to the `nav:` tree in `mkdocs.yml`.**
- `docs/tables/` documents the `MPE_*` control tables (see naming conventions below).
- `docs/img/` holds images; `docs/video/` holds video assets; `docs/marketing/` holds flyers/PDFs.
- `theme/` is the custom Material theme override; `slides/` and `slides.md` are the presentation deck.

## Page conventions

- Each page starts with YAML front matter: `layout: article`, `title`, `description`, and usually `og_image`. Match the style of existing pages.
- `description` is used for SEO and social cards - write a single, complete sentence.
- Reference images with root-relative paths (e.g. `/img/foo.png`) or relative paths consistent with neighbouring pages.
- This site uses these `markdown_extensions`: `admonition`, `pymdownx.superfences`, `codehilite`, `meta`, and `toc` (with permalinks). Use fenced code blocks with language hints (`sas`, `js`, `bash` are highlighted); use admonitions (`!!! note`) for callouts.
- Internal links use the page slug with a trailing slash (e.g. `/dcc-validations/`), matching existing cross-references.

## MPE table docs (`docs/tables/`)

Control tables are documented one file per table, named `mpe_<name>.md`, and registered under the "Table Guide" section of `nav:` in `mkdocs.yml`. Follow the existing pattern:

- Front matter with a `description` explaining what the table configures.
- A short intro paragraph, then a link to the relevant configuration guide.
- A `## Columns` list. Prefix primary-key / business-key columns with the 🔑 emoji, and give each column as `` `NAME type` ``: description. SCD2 tables carry `TX_FROM`/`TX_TO` as the first two columns.

## Writing style

Use regular dashes (`-`) in content, not em-dashes. Do not hard-wrap Markdown: each paragraph, list item and heading is a single logical line, regardless of length - let the renderer soft-wrap. This keeps diffs clean.

## Building

- `pip install mkdocs mkdocs-material mkdocs-redirects` (see `build.sh` / `mkdocs.yml` for the exact plugin list).
- `mkdocs serve` for a live-reloading local preview; `mkdocs build` (or `./build.sh`) to produce the static site.
- After adding or renaming a page, confirm it appears in the `nav:` tree and that `mkdocs build` reports no warnings about missing/orphaned files.

## Git

Do NOT auto-commit or push. Leave changes in the working tree for the user to review and commit.