dc/AGENTS.md

Agent Instructions

Read CONTEXT.md at the repo root first - it is the domain glossary and orientation for Data Controller (roles, load types, MPE control tables, validations, security). Use its vocabulary in your output.

Related repositories

Data Controller spans three sibling repos (usually checked out side by side):

• dc (this repo) - the product source (Angular client + SAS backend).
• docs.datacontroller.io - the user-facing product documentation (MkDocs). User-facing behaviour is documented there; the .agents/docs/ deep-dives here link out to it.
• datacontroller.io - the marketing site, blog and feed (Gatsby).

Git

Do NOT auto-commit. Never run git commit (or git push) unless the user explicitly asks. Leave changes in the working tree for the user to review and commit themselves.

CHANGELOG and versioning

Do NOT edit CHANGELOG.md by hand, and do NOT bump the version in package.json. The release pipeline (semantic-release, in .gitea/workflows/release.yaml) generates both automatically from Conventional Commit messages on every push to main. Manual entries collide with the pipeline's release commit and are overwritten anyway. Control the changelog through your commit messages instead. See .agents/docs/releases-and-changelog.md.

Markdown files

Do NOT hard-wrap Markdown files (no fixed-width line wrapping / carriage returns inside paragraphs). Each paragraph, list item, and heading should be a single logical line, regardless of length. Let the editor/viewer soft-wrap. This includes AGENTS.md itself.

This is different from .sas files, where a maximum line length applies. The no-wrap rule applies to all *.md files in this repo (docs, READMEs, etc.).

Rationale: hard-wrapped prose produces noisy diffs when sentences are edited and reflowed, and Markdown renderers already handle wrapping.

Linting (required before "done")

Never consider a change complete until the relevant linters pass on the files you touched — do not rely on the user's pre-commit hooks to catch it:

• Client (TypeScript/HTML/etc.): run npm run lint:check from the client/ directory (prettier). Fix any failures with npm run lint:fix.
• SAS: after creating or modifying any .sas files, run sasjs lint from the sas/ directory and ensure the files you touched have no lint warnings (the repo currently has pre-existing warnings in other files, which can be ignored). sas/.sasjslint carries ignoredMacros: ["webout", "mpeinit", "mpeterm"]. webout is the linter's own default - sasjs compile injects %webout into every service - and an explicit list replaces that default, so it has to be restated there. mpeinit and mpeterm are listed because every service is compiled with a serviceInit program (sasjs/utils/serviceinitsas9|viya|server.sas) that declares both macros in its own header, so a service body may call them without declaring them. Add a macro to that list only when it reaches a file the same way - injected by the compiler, through serviceInit, testSetUp or another implicit provider - never to silence a genuinely missing declaration. noBannedStrings flags the literal words error and warning anywhere in a file, comments included. Reword prose; where the text has to stay (a real %put, a doxygen @warning tag), keep the log output identical with %put %str(WARN)ING: rather than a per-file override, and use @sasjslint {"noBannedStrings": false} only when the word itself is the content.

No external assets

Data Controller must run entirely locally (offline / on-prem, no internet access). The built product must never fetch assets from remote servers — no external fonts, images, scripts, stylesheets, CDN links, or remote URLs in meta tags (e.g. og:image, og:url, itemprop="image"). All assets must be bundled and served locally.

The .agents folder

Agent-related content lives in .agents/: technical/agent-facing documentation goes in .agents/docs/ (not docs/), and skills in .agents/skills/. When writing explanatory or technical docs about the codebase, put them in .agents/docs/.

Skills installed via npx skills add are tracked in skills-lock.json and live under .agents/skills/. Repo-local custom skills (e.g. dc-sas for Data Controller SAS development, dc-estate-testing for estate deploys and test runs, handsontable, hyperformula) are kept here too. Avoid editing npx-managed skill files directly — use npx skills update instead.

Code comments and test names

Never reference items that are not active parts of the repository — no "the original bug", "regression from this fix", "this session/PR/commit", or similar ephemeral context. Comments and test names must be self-contained: describe the behaviour being asserted, not the history of how it was discovered. The one exception is a literal link to a ticket/issue tracker.