@attalabs/vinaya 0.22.0 → 0.24.0

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/node-route.ts

@@ -0,0 +1,134 @@
+/**
+ * The single node → `/docs` route derivation. Nav construction
+ * (`load-aeg-docs.ts`), the "Read more" resolver (`read-more.ts`), and the
+ * harness map (`/docs` `page.tsx`) all resolve a `DiagramNode` to its docs
+ * location through THIS function — one source of truth, so a card's deep-link,
+ * a "Read more" anchor, and a ring/action page's heading `id` can never point
+ * at three different places for the same node. A parallel, hand-maintained
+ * slug list is the exact failure mode this replaces (the same discipline
+ * `surfaced-manifest.ts` holds for the file allowlist).
+ *
+ * Granularity follows content size. A role or contract is a whole
+ * `aeg-root/**.md` file, so it keeps its own page and needs no anchor. A gate
+ * or check is one row of `enforcement.md`, and an action is one entry of
+ * `ACTIONS`, so each is an `#`-anchored section inside a grouping page
+ * (`/docs/rings/ring-<n>` or `/docs/actions`).
+ *
+ * The anchor slug is recomputed here from the node's DISPLAY form, not read
+ * verbatim off the node id. `node.id`/`node.label` keep the full doctrine
+ * text — G-codes included — because the registry check (G1-G5,
+ * `registry-checks.ts`) matches on that exact id; a slug that a reader
+ * follows into a URL fragment has no such constraint, so it is cleaned at
+ * this one edge instead. Both the heading (`humanLabel`/`shortLabel`, in
+ * `apps/vinaya/web`) and this anchor apply the same two rules — strip a
+ * leading G-code, cut a pathologically long name at its first clause — so a
+ * heading and its anchor still agree, just no longer byte-identical to the
+ * doctrine id. A node whose display form needs no cleanup still gets the
+ * same slug it always did, since stripping/cutting are no-ops on it.
+ *
+ * Zero I/O, additive export — takes an already-derived node, returns data,
+ * never reads a file (aeg-core purity, #372/#382/#506).
+ */
+
+import type { DiagramNode } from '../diagram-model'
+
+export type NodeDocRoute = {
+  /** The page a node lives on. */
+  route: string
+  /** The heading anchor within that page, or `null` for a file-sized node
+   * (role/contract) that owns its whole page. */
+  slug: string | null
+}
+
+/** A pathologically long anchor is cut at its first clause boundary rather
+ * than published whole. 100 is chosen against the current doctrine, not a
+ * round guess: the longest anchor slug outside the one row this exists to
+ * fix is 84 characters (a ring-0 gate's compound name), so 100 leaves that
+ * row untouched while still catching genuinely oversized names — the one
+ * 127-character row this was written for included. */
+const MAX_ANCHOR_SLUG_LENGTH = 100
+
+/** Strips a leading `g<n>-` code off an already-slugified anchor. Operates on
+ * the slug form (not `node.label`) so a node whose id isn't `slugify(label)`
+ * to begin with — an `action`, whose id is the hand-authored `ACTIONS` entry
+ * id, not a re-derivation of its label — is never touched: no G-coded or
+ * over-length action exists today, so this function is a no-op for every one
+ * of them, exactly preserving their existing anchors. */
+function stripGCodeSlug(slug: string): string {
+  return slug.replace(/^g\d+-/, '')
+}
+
+/** Strips the same `G<n> — ` doctrine code off raw label text, for the
+ * over-length fallback below. Same contract as `humanLabel` in
+ * `apps/vinaya/web`'s `display-label.ts` (duplicated rather than shared:
+ * aeg-core cannot import from the web app, and this rule is small enough
+ * that keeping two copies in sync by inspection is cheaper than a new
+ * cross-package export). */
+function stripGCodeLabel(label: string): string {
+  return label.replace(/^G\d+\s*—\s*/, '')
+}
+
+/** Cuts at the first clause boundary, same separator set `shortLabel` uses
+ * in `display-label.ts` — kept in sync with that function's comment by
+ * inspection, for the same reason `stripGCodeLabel` is duplicated above. */
+function firstClause(label: string): string {
+  return label.split(/ \(| \/ |—|–|: /)[0]?.trim() ?? label
+}
+
+/** Same cleanup `diagram-model.ts`'s own (private, un-exported) `slugify`
+ * applies when it stamps a node id — duplicated here rather than imported so
+ * this file never needs `diagram-model.ts` to export it. Reached only by the
+ * over-length fallback below, never by the common case. */
+function slugifyText(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/`/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+}
+
+/** The anchor slug for a node's display form. Strips a G-code off the
+ * existing id-stamped slug first — a byte-preserving operation for every
+ * node that never had one. Only if the result is STILL too long to publish
+ * does this fall back to re-deriving a short slug from `node.label`'s first
+ * clause; that fallback is the one path that can produce a slug other than
+ * a prefix of the id-stamped one, and today only one row (a 127-character
+ * ring-0 gate name) reaches it. */
+function nodeSlug(node: DiagramNode): string {
+  const rawSlug = node.id.slice(node.kind.length + 1)
+  const stripped = stripGCodeSlug(rawSlug)
+  if (stripped.length <= MAX_ANCHOR_SLUG_LENGTH) return stripped
+  return slugifyText(firstClause(stripGCodeLabel(node.label)))
+}
+
+/**
+ * Resolve a node to its `/docs` route + anchor slug. Returns `null` for a kind
+ * with no docs surface (there is none today — every kind resolves).
+ */
+export function nodeDocRoute(node: DiagramNode): NodeDocRoute | null {
+  switch (node.kind) {
+    case 'role':
+      return { route: `/docs/roles/${node.label}`, slug: null }
+    case 'contract':
+      return { route: `/docs/contracts/${node.label}`, slug: null }
+    case 'gate':
+    case 'check':
+      if (node.ringIndex === undefined) return null
+      return { route: `/docs/rings/ring-${node.ringIndex}`, slug: nodeSlug(node) }
+    case 'action':
+      return { route: '/docs/actions', slug: nodeSlug(node) }
+    case 'ring':
+      if (node.ringIndex === undefined) return null
+      return { route: `/docs/rings/ring-${node.ringIndex}`, slug: null }
+    default:
+      return null
+  }
+}
+
+/** The full in-app href — `route` plus a `#slug` fragment when the node is an
+ * anchored section. The form the map and `read-more.ts` link to directly. */
+export function nodeDocHref(node: DiagramNode): string | null {
+  const resolved = nodeDocRoute(node)
+  if (!resolved) return null
+  return resolved.slug ? `${resolved.route}#${resolved.slug}` : resolved.route
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/parse-doc.ts

@@ -0,0 +1,43 @@
+import matter from 'gray-matter'
+import type { DocFrontmatter } from './types'
+
+export type ParsedDoc = {
+  frontmatter: DocFrontmatter
+  body: string
+  firstH1?: string
+}
+
+const H1_PATTERN = /^\s*#\s+(.+?)\s*$/m
+
+export function parseDocFrontmatter(raw: string): ParsedDoc {
+  const { data, content } = matter(raw)
+  const fm = data as Record<string, unknown>
+
+  const frontmatter: DocFrontmatter = {}
+  if (typeof fm.title === 'string') frontmatter.title = fm.title
+  if (typeof fm.sidebarTitle === 'string') {
+    frontmatter.sidebarTitle = fm.sidebarTitle
+  } else if (typeof fm.sidebar_title === 'string') {
+    frontmatter.sidebarTitle = fm.sidebar_title
+  }
+  if (typeof fm.description === 'string') frontmatter.description = fm.description
+  if (typeof fm.section === 'string') frontmatter.section = fm.section
+  if (typeof fm.order === 'number') frontmatter.order = fm.order
+  if (typeof fm.parent === 'string') frontmatter.parent = fm.parent
+  if (typeof fm.surfaced === 'boolean') frontmatter.surfaced = fm.surfaced
+
+  const h1Match = content.match(H1_PATTERN)
+  const firstH1 = h1Match?.[1]?.trim()
+
+  return { frontmatter, body: content, firstH1 }
+}
+
+export function deriveTitle(parsed: ParsedDoc, fallbackFromPath: string): string {
+  if (parsed.frontmatter.title) return parsed.frontmatter.title
+  if (parsed.firstH1) return parsed.firstH1
+  return fallbackFromPath
+}
+
+export function stripLeadingH1(body: string): string {
+  return body.replace(/^\s*#\s+.*\n+/, '')
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/published-prose.ts

@@ -0,0 +1,306 @@
+/**
+ * C7 — the published-prose check. Pure and zero-I/O, shaped like
+ * `docs-coherence.ts` (parsed entries plus the model-backed surfaced-path
+ * allowlist in, `{ errors, notes }` out).
+ *
+ * A role or contract doc is read by two audiences with opposite needs: an
+ * agent taking the role reads it end to end as its operating instruction, and
+ * a person landing on `/docs/roles/<id>` reads the same file cold. The answer
+ * is one short, binding section at the top of every role and contract — `##
+ * The short version` — which is what publishes; everything under `##
+ * Reference` explains it and stays in the repo. This check enforces two
+ * properties of that section, over the published set only:
+ *
+ *   1. **Structure** — every surfaced `roles/*.md` and `contracts/*.md` opens
+ *      with a `## The short version` section carrying all four bold-led
+ *      blocks, in order, inside the word band. The blocks answer the same four
+ *      questions for a role and for a seam (what it owns/carries, when it
+ *      refuses, what it never does, how it physically runs), which is why the
+ *      lead-ins differ by kind but the count and order never do.
+ *   2. **Readability** — the text that actually reaches a reader carries no
+ *      token a stranger cannot resolve from the page: no decision id, no
+ *      section sign, no forge number, no retired public name, no tranche
+ *      slug, no repo-internal path, and no label vocabulary (namespaced or
+ *      retired alike — a published page should name neither, and flagging only
+ *      the current grammar would leave every retired mention invisible).
+ *
+ * **What "published" means here is deliberately narrow.** For a role or
+ * contract it is the short version, not the file. For `enforcement.md` it is
+ * the introduction plus the four columns the page renders — the row's own
+ * name, `Summary`, `Category`, `Description`. The enforcing columns (`Gate`,
+ * `What must be true…`, `Re-verifies`, `Runs`, `Catches`, `implementation`,
+ * `lock`) are never scanned: they never reach a page, and flagging them would
+ * demand rewriting the gate registry to suit a website. Columns resolve by
+ * HEADER NAME, never by index — the three ring tables have different shapes,
+ * and `Summary`/`Category`/`Description` are the ones spelled identically in
+ * all three, the same property `registry-parse.ts` relies on for
+ * `Description`.
+ *
+ * **Protocol mechanics are published on purpose.** `.worktrees/task/<tranche>/<n>`
+ * and the `task/<tranche>/<n>` branch convention are the method an adopter
+ * must learn, not this repo's internals — they are masked out before scanning
+ * so a path rule can never eat them, and that exemption is tested rather than
+ * incidental.
+ */
+
+import { findHeadingLine, findTable } from '../markdown-table'
+import { isSurfacedDoc } from './surfaced-manifest'
+import type { DocFrontmatter } from './types'
+
+export const SHORT_VERSION_HEADING = 'The short version'
+export const REFERENCE_HEADING = 'Reference'
+
+/** Words. Under the floor means something was dropped; over the ceiling means
+ * the reference is being summarised instead of the rule being stated. */
+export const SHORT_VERSION_MIN_WORDS = 150
+export const SHORT_VERSION_MAX_WORDS = 450
+
+/** The four blocks, in order, as a role answers them. */
+export const ROLE_BLOCKS = ['You own', 'You refuse', 'You never', 'How it physically runs'] as const
+
+/** The same four blocks, as a seam answers them. */
+export const CONTRACT_BLOCKS = [
+  'What crosses',
+  'The hand-off is malformed',
+  'What it does not carry',
+  'How it physically runs'
+] as const
+
+/**
+ * Protocol facts that must survive every readability rule. Masked out of the
+ * text before scanning, longest first, so a repo-internal-path rule can never
+ * claim the branch convention.
+ */
+export const ALLOWED_MECHANICS: readonly string[] = [
+  '.worktrees/task/<tranche>/<n>',
+  'task/<tranche>/<n>',
+  '.worktrees/'
+]
+
+export type PublishedProseEntry = {
+  /** Path relative to `aeg-root/`, e.g. `roles/developer.md`. */
+  relPath: string
+  frontmatter: Pick<DocFrontmatter, 'surfaced' | 'title' | 'description'>
+  body: string
+}
+
+export type PublishedProseResult = { errors: string[]; notes: string[] }
+
+type ProseRule = { id: string; what: string; pattern: RegExp }
+
+/**
+ * Every rule is case-sensitive on purpose where the token itself is: forge
+ * labels are lower-case, so a lower-case-only match keeps a capitalized
+ * English word ("Project:", the PR-body field) from being read as the deleted
+ * `project:*` label family.
+ */
+const PROSE_RULES: ProseRule[] = [
+  { id: 'decision-id', what: 'a decision id', pattern: /\bD-\d{3,}\b/ },
+  { id: 'section-ref', what: 'a section reference', pattern: /§/ },
+  { id: 'forge-number', what: 'a forge number', pattern: /#\d+/ },
+  { id: 'retired-name', what: 'the retired public name', pattern: /\bAEG\b/ },
+  { id: 'tranche-slug', what: 'a tranche slug', pattern: /\b[a-z][a-z0-9]*(?:-[a-z0-9]+)+-v\d+\b/ },
+  {
+    id: 'label-vocabulary',
+    what: 'forge label vocabulary',
+    // Every entry here is CUMULATIVE — a retired namespace stays banned after
+    // the objects carrying it are gone, because a published page naming it is
+    // just as unreadable to a stranger as one naming the current grammar (see
+    // the module header). `aeg:` is retired and still listed for that reason,
+    // and `iteration:` joins it: the rename to `tranche:` ADDS an alternative,
+    // it does not substitute one. Substituting is how a rename silently
+    // narrows this gate — the forge still carried `vinaya/iteration:*` labels
+    // when the rename landed, and a page naming one would have passed.
+    pattern: /(?:vinaya\/)?\b(?:tranche|iteration|tier|needs|waiver|project|aeg):(?![/\s]|$)/
+  },
+  { id: 'internal-path', what: 'a repo-internal path', pattern: /\b(?:packages|apps|aeg-root|tools|scripts)\// },
+  { id: 'internal-path', what: 'a repo-internal path', pattern: /\.(?:claude|husky|github)\// },
+  {
+    id: 'internal-path',
+    what: 'a repo-internal file',
+    pattern: /(?:^|[\s(`"'[])[\w.-]+(?:\/[\w.-]+)*\.(?:ts|tsx|js|jsx|mjs|cjs|sh|ya?ml|json|md)\b/
+  }
+]
+
+/** The doc kinds this check governs, and the block set each answers with. */
+function blocksFor(relPath: string): readonly string[] | null {
+  if (relPath.startsWith('roles/')) return ROLE_BLOCKS
+  if (relPath.startsWith('contracts/')) return CONTRACT_BLOCKS
+  return null
+}
+
+function sectionBody(body: string, heading: string): string | null {
+  const lines = body.split('\n')
+  const start = lines.findIndex((line) => line.trim() === `## ${heading}`)
+  if (start === -1) return null
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => /^##\s/.test(line))
+  return (end === -1 ? rest : rest.slice(0, end)).join('\n').trim()
+}
+
+/**
+ * The section a role/contract page publishes, or null when the doc carries
+ * none. The single extraction both the gate and Vinaya's `/docs` renderer
+ * read, so the page and the check can never disagree about what "published"
+ * means.
+ */
+export function extractShortVersion(body: string): string | null {
+  return sectionBody(body, SHORT_VERSION_HEADING)
+}
+
+/**
+ * What a role/contract page renders, with a degradation ladder that never
+ * leaks the reference: the short version when present; otherwise the body
+ * above `## Reference`; otherwise the whole body (a doc with neither heading
+ * is not governed by C7's structure rule and has no reference to hide).
+ */
+export function publishedDoctrineBody(body: string): string {
+  const short = extractShortVersion(body)
+  if (short !== null) return short
+  const lines = body.split('\n')
+  const referenceAt = lines.findIndex((line) => line.trim() === `## ${REFERENCE_HEADING}`)
+  return referenceAt === -1 ? body : lines.slice(0, referenceAt).join('\n').trim()
+}
+
+export function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length
+}
+
+function maskAllowedMechanics(text: string): string {
+  let masked = text
+  for (const literal of ALLOWED_MECHANICS) {
+    masked = masked.split(literal).join(' ')
+  }
+  return masked
+}
+
+/**
+ * The four columns `enforcement.md` actually renders — the row's own name plus
+ * `Summary`, `Category`, `Description` — and the introduction above the first
+ * ring. Everything else in those tables is enforcing text that never reaches a
+ * page.
+ */
+export function enforcementPublishedText(content: string): string[] {
+  const lines = content.split('\n')
+  const out: string[] = []
+
+  const firstRing = lines.findIndex((line) => /^##\s+Ring 0\b/.test(line))
+  out.push((firstRing === -1 ? lines : lines.slice(0, firstRing)).join('\n'))
+
+  const publishedHeaders = ['summary', 'category', 'description']
+  for (const ring of [0, 1, 2]) {
+    const headingLine = findHeadingLine(lines, new RegExp(`^##\\s+Ring ${ring}\\b`))
+    if (headingLine === null) continue
+    const table = findTable(lines, headingLine + 1)
+    if (!table) continue
+    const indices = publishedHeaders
+      .map((name) => table.headers.findIndex((h) => h.trim().toLowerCase() === name))
+      .filter((i) => i !== -1)
+    for (const row of table.rows) {
+      out.push(row.cells[0] ?? '')
+      for (const i of indices) out.push(row.cells[i] ?? '')
+    }
+  }
+
+  return out.filter((text) => text.trim().length > 0)
+}
+
+/**
+ * The readability rules, callable on any published text — not just a doc body.
+ *
+ * Exported because `/docs/actions` renders prose that lives in TypeScript
+ * (`ACTIONS` in `actions.ts`), not in a markdown file, so `evaluatePublishedProse`
+ * never sees it. A whole published page was unguarded on that technicality;
+ * `actions.test.ts` closes it by running this over every entry.
+ */
+export function readabilityErrors(where: string, texts: string[]): string[] {
+  const errors: string[] = []
+  checkReadability(where, texts, errors)
+  return errors
+}
+
+function checkReadability(where: string, texts: string[], errors: string[]): void {
+  const seen = new Set<string>()
+  for (const raw of texts) {
+    const text = maskAllowedMechanics(raw)
+    for (const rule of PROSE_RULES) {
+      const match = text.match(rule.pattern)
+      if (!match) continue
+      const token = (match[0] ?? '').trim()
+      const key = `${rule.id}:${token}`
+      if (seen.has(key)) continue
+      seen.add(key)
+      errors.push(`C7: published text in "${where}" contains ${rule.what} a reader cannot resolve: "${token}"`)
+    }
+  }
+}
+
+function checkStructure(relPath: string, body: string, blocks: readonly string[], errors: string[]): void {
+  const short = extractShortVersion(body)
+  if (short === null) {
+    errors.push(
+      `C7: surfaced doc "${relPath}" has no "## ${SHORT_VERSION_HEADING}" section — the published page would have nothing binding to show a reader`
+    )
+    return
+  }
+
+  let cursor = 0
+  for (const block of blocks) {
+    const at = short.indexOf(`**${block}`, cursor)
+    if (at === -1) {
+      errors.push(`C7: "${relPath}" short version is missing the "${block}" block (all four blocks always appear)`)
+      continue
+    }
+    cursor = at + block.length
+  }
+
+  const words = countWords(short)
+  if (words < SHORT_VERSION_MIN_WORDS) {
+    errors.push(
+      `C7: "${relPath}" short version is ${words} words, under the ${SHORT_VERSION_MIN_WORDS}-word floor — something was dropped`
+    )
+  } else if (words > SHORT_VERSION_MAX_WORDS) {
+    errors.push(
+      `C7: "${relPath}" short version is ${words} words, over the ${SHORT_VERSION_MAX_WORDS}-word ceiling — state the rule, don't summarise the reference`
+    )
+  }
+}
+
+/**
+ * Runs both checks over the published set only. `entries` may hold every doc
+ * under `aeg-root/`; `surfacedPaths` (the model-backed allowlist) is what
+ * narrows it, so this check can never publish-check a doc the site does not
+ * publish, nor miss one it does.
+ */
+export function evaluatePublishedProse(
+  entries: PublishedProseEntry[],
+  surfacedPaths: ReadonlySet<string> = new Set()
+): PublishedProseResult {
+  const errors: string[] = []
+  const notes: string[] = []
+
+  const surfaced = entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths))
+
+  for (const entry of surfaced) {
+    // Frontmatter renders too: `title` is the page heading and the sidebar
+    // entry, `description` is the page metadata. Checking only the body left
+    // both unguarded — a citation in a title reaches a reader exactly as
+    // surely as one in a paragraph.
+    checkReadability(entry.relPath, [entry.frontmatter.title ?? '', entry.frontmatter.description ?? ''], errors)
+
+    const blocks = blocksFor(entry.relPath)
+    if (blocks) {
+      checkStructure(entry.relPath, entry.body, blocks, errors)
+      const short = extractShortVersion(entry.body)
+      if (short !== null) checkReadability(entry.relPath, [short], errors)
+      continue
+    }
+    if (entry.relPath === 'enforcement.md') {
+      checkReadability(entry.relPath, enforcementPublishedText(entry.body), errors)
+    }
+  }
+
+  if (surfaced.length === 0) notes.push('C7: no surfaced docs to check.')
+
+  return { errors, notes }
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/surfaced-manifest.ts

@@ -0,0 +1,89 @@
+/**
+ * The canonical "surfaced doc" manifest for `aeg-root/`. Defines, as
+ * data, which docs a public AEG page shows. The rule is **model-backed**: a
+ * doc is surfaced if and only if a `DiagramModel` node points at it.
+ * The same `DiagramModel` that `/docs/harness` renders is the allowlist for
+ * `/docs/reference` — the two surfaces are two renderers of one model, and the doc that
+ * backs no reachable node stops being public, every build.
+ *
+ * The node→doc mapping (`modelBackedDocPaths`) is the same one `read-more.ts`
+ * uses to resolve a node's "Read more" target: gate/check nodes back
+ * `enforcement.md`; a role node backs `roles/<id>.md`; a contract node backs
+ * `contracts/<id>.md`. `action`/`ring` nodes back no `aeg-root/**` document
+ * (an action's source is `packages/aeg-core/src/actions.ts`, a ring is a
+ * summary label), so they add nothing to the set. Today that is 16 files —
+ * `enforcement.md` + the 9 `roles/*.md` + the 6 `contracts/*.md`.
+ *
+ * This is the single source of truth the C6 docs-coherence check
+ * (`docs-coherence.ts`) and Vinaya's `/docs` loader both consume. There is
+ * **no second, path-based exclusion rule** — a competing rule is the failure
+ * mode this manifest exists to prevent, and the model-backed set replaced the
+ * old path-exclusion rules outright rather than sitting beside them. The only
+ * escape hatch is the per-doc `surfaced` frontmatter override, which wins in
+ * both directions.
+ *
+ * Purity: this module imports only the `DiagramModel` **type** from the
+ * diagram layer — no runtime coupling, no I/O. The doctrine is read (and the
+ * model derived) by the caller, which passes the derived path set in; aeg-core
+ * stays zero-I/O (#372/#382/#506).
+ *
+ * Paths are relative to `aeg-root/` (e.g. `roles/developer.md`), matching
+ * `DocFrontmatter`'s existing convention.
+ */
+
+import type { DiagramModel } from '../diagram-model'
+import type { DocFrontmatter } from './types'
+
+/**
+ * The set of `aeg-root/`-relative doc paths a `DiagramModel` points at — the
+ * allowlist. Mirrors `read-more.ts`'s `docRoute` resolution exactly, so
+ * `/docs/reference`'s surfaced set and `/docs/harness`'s "Read more" targets can never
+ * name different files: gate/check → `enforcement.md`, role → `roles/<id>.md`,
+ * contract → `contracts/<id>.md`. A node's `label` is its doctrine id
+ * (`role.roleId` / `contract.contractId`), and every `roles/*.md` /
+ * `contracts/*.md` file is named `<id>.md` — one convention backs both the
+ * GitHub path and the docs route.
+ */
+export function modelBackedDocPaths(model: DiagramModel): Set<string> {
+  const paths = new Set<string>()
+  for (const node of model.nodes) {
+    if (node.kind === 'gate' || node.kind === 'check') paths.add('enforcement.md')
+    else if (node.kind === 'role') paths.add(`roles/${node.label}.md`)
+    else if (node.kind === 'contract') paths.add(`contracts/${node.label}.md`)
+  }
+  return paths
+}
+
+const NO_MODEL_BACKED_PATHS: ReadonlySet<string> = new Set()
+
+/**
+ * Whether `relPath` (relative to `aeg-root/`) is a surfaced doc. A boolean
+ * `surfaced` frontmatter field always wins over the model — the escape hatch
+ * in both directions. Otherwise the doc is surfaced iff it is in
+ * `surfacedPaths` (the model-backed allowlist from `modelBackedDocPaths`).
+ *
+ * `surfacedPaths` is optional so a caller that has no model surfaces nothing
+ * by default rather than everything — the safe direction for a rule whose
+ * whole point is that a doc publishes only when a node points at it.
+ */
+export function isSurfacedDoc(
+  relPath: string,
+  frontmatter: Pick<DocFrontmatter, 'surfaced'>,
+  surfacedPaths: ReadonlySet<string> = NO_MODEL_BACKED_PATHS
+): boolean {
+  if (typeof frontmatter.surfaced === 'boolean') return frontmatter.surfaced
+  return surfacedPaths.has(relPath)
+}
+
+export type SurfacedManifestEntry = {
+  relPath: string
+  frontmatter: Pick<DocFrontmatter, 'surfaced'>
+}
+
+/** Filters a list of parsed doc entries down to the surfaced subset. */
+export function surfacedDocs(
+  entries: SurfacedManifestEntry[],
+  surfacedPaths: ReadonlySet<string> = NO_MODEL_BACKED_PATHS
+): string[] {
+  return entries.filter((e) => isSurfacedDoc(e.relPath, e.frontmatter, surfacedPaths)).map((e) => e.relPath)
+}

package/studio-standalone/_node_modules/@attalabs/aeg-core/src/docs/types.ts

@@ -0,0 +1,33 @@
+export type DocFrontmatter = {
+  title?: string
+  sidebarTitle?: string
+  description?: string
+  section?: string
+  order?: number
+  parent?: string
+  surfaced?: boolean
+}
+
+export type Doc = {
+  slug: string
+  title: string
+  sidebarTitle?: string
+  description?: string
+  section: string
+  order: number
+  href: string
+  filePath: string
+  children?: Doc[]
+  parentSlug?: string
+}
+
+export type DocSection = {
+  id: string
+  label: string
+  docs: Doc[]
+}
+
+export type DocNav = {
+  sections: DocSection[]
+  flat: Doc[]
+}