docs.datacontroller.io/AGENTS.md

Agent Instructions

This repository is the user-facing documentation for Data Controller for SAS®, published at docs.datacontroller.io. It is a MkDocs 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.