docs: add CWL agent guidance to AGENTS.md

AGENTS.md

@@ -38,3 +38,72 @@ parameter calibration and test linking.
 - Isolate operational fixes (workflow/docs/dependency policy) from algorithmic
   edits.
 - Document assumptions and risk in commit/PR summaries.
+
+## Product design and Figma
+
+- This repo has no frontend, route tree, Figma file, or implemented visual
+  surface. Do not create UI code or visual artifacts unless a real product
+  surface is introduced.
+- Do not call future Figma work a "design system" unless it includes reusable
+  foundations, tokens, components, states, accessibility guidance, and code
+  mapping. Otherwise call it a UI kit, wireframe, or draft.
+
+<!-- BEGIN cwl-agent-guidance -->
+## Agent guidance (CWL governance)
+
+Applies to every agent (Claude, Codex, Cursor, opencode, ...) working in this repo.
+
+### Security & review gate
+
+- Every PR runs a central **Security Scan** required check: `osv-scan` +
+  `dependency-review` (diff-scoped) and `trivy-fs` (repo-wide, CRITICAL/HIGH,
+  fixable only). It runs against each PR base, **including stacked PRs**.
+- A failing `trivy-fs` is a **REAL finding, not a flake.** Read the job log (it
+  prints each finding's rule id, severity, and file) or the run's SARIF results,
+  then **remediate**: bump the offending R dependency (this package vendors its
+  library tree under `packrat/`), or, only for a genuine false positive, add a
+  narrow, path-scoped, commented entry to `.trivyignore.yaml`. Never weaken or
+  disable the gate. This repo has no Dockerfile or k8s manifests, so misconfig
+  findings are not expected; a hit here is a dependency or secret finding.
+- The vendored packrat openssl docs include a verified false-positive example
+  key at `packrat/lib/x86_64-pc-linux-gnu/3.4.1/openssl/doc/keys.html`; keep
+  its `private-key` suppression path-scoped in `.trivyignore.yaml` and do not
+  blanket-ignore the rule.
+- A local `trivy` scan with a stale DB misses findings: run
+  `trivy --download-db-only` first, and scan the **merge ref**, not just the PR head.
+- The org `code_scanning` ruleset is intentionally **CodeQL-only** (multiple
+  code-scanning tools cannot converge on one PR ref). Gating is by the Security
+  Scan **job result**, not the `code_scanning` rule; do not add tools to that rule.
+
+### Code exploration
+
+- There is no `.codegraph/` index in this repo, so use normal search
+  (grep/find) to locate and understand code. If a `.codegraph/` index is added
+  later, prefer CodeGraph (`codegraph explore "<query>"` or the
+  code-review-graph MCP tools) before grep/find; it surfaces callers, callees,
+  and impact that text search misses.
+
+### This repo's role in the ecosystem
+
+- **aFIPC**: R IRT package for Fixed-Item Parameter Calibration; feeds
+  fast-mlsirm's psychometrics.
+- The org is an ecosystem around **naruon** (the hub: an email/PIM app that
+  DOM-decomposes emails and files into a persisted knowledge graph). Every
+  component is a **standalone program that must ALSO work as a git submodule**,
+  grown separately and together.
+- Sibling components: **waf-ids-ai-soc** (WAF/IDS/AI SOC/LB/APIM),
+  **clearfolio** (document viewer), **pg-erd-cloud** (ERD tool),
+  **contextual-orchestrator** (LLM cost/perf/upstream-LB gateway, beyond
+  LiteLLM), **codec-carver** (STT/omni-modal speech-video codec),
+  **fast-mlsirm** (LLM-as-a-Judge calibration + evaluation-item quality; uses
+  aFIPC FIPC + kaefa item-fit), **feelanet-adfs** (passwordless SSO:
+  OIDC/SCIM/ADFS/LDAP/FIDO2/OAuth2.1, eliminate passwords), **newsdom-api**
+  (PDF to DOM sidecar), **semantic-data-portal** (upper ontology/catalog/governance
+  plane with its own graph engine).
+
+### Research grounding
+
+- For substantive calibration/linking changes, cite the relevant IRT and
+  psychometrics literature. Commit paper PDFs only when redistribution is
+  permitted; otherwise cite, link, and summarize.
+<!-- END cwl-agent-guidance -->