@rubytech/create-maxy-code 0.1.441 → 0.1.443

package/payload/platform/docs/superpowers/plans/2026-07-14-graph-top-level-labels-ontology-single-source.md

@@ -0,0 +1,458 @@
+# Graph top-level label allowlist ontology single-source — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the `/graph` filter-popover chip allowlist (and the two other server routes that read the same set) derive from each vertical's `## Top-level node types` schema table instead of the hardcoded `FILTER_TOP_LEVEL_LABELS`, so a top-level label added to a vertical schema surfaces as a chip with no TypeScript edit, while preserving today's exact chip visibility.
+
+**Architecture:** A new server-only module `platform/ui/server/lib/top-level-labels.ts` reads every `platform/plugins/memory/references/schema-*.md`, extracts the `Neo4j Label` column of each file's `## Top-level node types` table, and unions those with an explicit `STATIC_TOP_LEVEL_LABELS` const (base-schema infra plus verticals lacking a top-level section). The three server routes (`graph-labels-in-graph`, `graph-subgraph`, `graph-default-view`) call `getTopLevelLabelAllowlist()` instead of importing `FILTER_TOP_LEVEL_LABELS`. Count-gating in the cypher is unchanged.
+
+**Tech Stack:** TypeScript (ES modules), Node `fs` (`readdirSync`/`readFileSync`), Vitest, Hono routes.
+
+## Global Constraints
+
+- Derived union MUST deep-equal today's `FILTER_TOP_LEVEL_LABELS` (48 members) against the real references dir — the byte-identical acceptance baseline.
+- No `schema:` namespace filter: every row of a `## Top-level node types` table contributes its `Neo4j Label`, so `WhatsAppGroup` (`cdm:Channel`) stays a chip.
+- The `Neo4j Label` column is resolved by header name, never by index (construction table has 5 columns, estate-agent 4).
+- The new module is server-only (reads files). `FILTER_TOP_LEVEL_LABELS` stays in `app/lib/graph-labels.ts` for the client `searchHelpers.ts`.
+- `getTopLevelLabelAllowlist()` returns a `ReadonlySet<string>` so `.has()` and spread work at every call site.
+- Observability line on computation: `op=top-level-labels source=ontology count=<n> files=<...> derived=<d> static=<s>`, written to stderr via `console.error`.
+- No em-dashes in any shipped log string. No task numbers in operator-visible strings or log lines.
+- Path resolution mirrors `server/index.ts`: `process.env.MAXY_PLATFORM_ROOT ?? join(__dirname, '..')`, then `plugins/memory/references`.
+
+---
+
+### Task 1: The derivation module and its regression test
+
+**Files:**
+- Create: `platform/ui/server/lib/top-level-labels.ts`
+- Test: `platform/ui/server/lib/top-level-labels.test.ts`
+
+**Interfaces:**
+- Produces: `getTopLevelLabelAllowlist(opts?: { referencesDir?: string }): ReadonlySet<string>` and `STATIC_TOP_LEVEL_LABELS: ReadonlySet<string>`.
+- Consumes: nothing from earlier tasks. Reads `FILTER_TOP_LEVEL_LABELS` from `../../app/lib/graph-labels` in the test only.
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// platform/ui/server/lib/top-level-labels.test.ts
+import { describe, it, expect } from 'vitest'
+import { resolve } from 'node:path'
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { getTopLevelLabelAllowlist } from './top-level-labels'
+import { FILTER_TOP_LEVEL_LABELS } from '../../app/lib/graph-labels'
+
+// The real shipped references directory (four hops up from this test file:
+// server/lib -> server -> ui -> platform -> plugins/memory/references).
+const REAL_REFERENCES = resolve(
+  import.meta.dirname,
+  '../../../plugins/memory/references',
+)
+
+describe('getTopLevelLabelAllowlist', () => {
+  it('deep-equals FILTER_TOP_LEVEL_LABELS against the real references dir', () => {
+    const derived = getTopLevelLabelAllowlist({ referencesDir: REAL_REFERENCES })
+    expect([...derived].sort()).toEqual([...FILTER_TOP_LEVEL_LABELS].sort())
+  })
+
+  it('surfaces a new top-level row with no TypeScript edit', () => {
+    const dir = mkdtempSync(resolve(tmpdir(), 'tll-'))
+    writeFileSync(
+      resolve(dir, 'schema-widgets.md'),
+      [
+        '# Widgets',
+        '',
+        '## Top-level node types (operator-entry, natural key)',
+        '',
+        '| Entity | Neo4j Label | Schema.org Type | Required Properties |',
+        '|--------|-------------|-----------------|---------------------|',
+        '| Widget | `Widget` | `schema:Product` | `accountId`, `sku` |',
+        '',
+      ].join('\n'),
+    )
+    const derived = getTopLevelLabelAllowlist({ referencesDir: dir })
+    expect(derived.has('Widget')).toBe(true)
+  })
+
+  it('includes a cdm:-namespaced top-level row (no namespace filter)', () => {
+    const dir = mkdtempSync(resolve(tmpdir(), 'tll-'))
+    writeFileSync(
+      resolve(dir, 'schema-transport.md'),
+      [
+        '## Top-level node types',
+        '',
+        '| Entity | Neo4j Label | Schema.org Type | Required Properties |',
+        '|--------|-------------|-----------------|---------------------|',
+        '| Channel | `SomeChannel` | `cdm:Channel` | `accountId`, `id` |',
+        '',
+      ].join('\n'),
+    )
+    const derived = getTopLevelLabelAllowlist({ referencesDir: dir })
+    expect(derived.has('SomeChannel')).toBe(true)
+  })
+
+  it('ignores tables that are not under a Top-level node types heading', () => {
+    const dir = mkdtempSync(resolve(tmpdir(), 'tll-'))
+    writeFileSync(
+      resolve(dir, 'schema-child.md'),
+      [
+        '## Child node types (reached via parent neighbourhood)',
+        '',
+        '| Entity | Neo4j Label | Schema.org Type | Required Properties |',
+        '|--------|-------------|-----------------|---------------------|',
+        '| Line | `QuoteLine` | `schema:Thing` | `accountId`, `id` |',
+        '',
+      ].join('\n'),
+    )
+    const derived = getTopLevelLabelAllowlist({ referencesDir: dir })
+    // Only the STATIC base labels survive; QuoteLine is a child, not top-level.
+    expect(derived.has('QuoteLine')).toBe(false)
+    expect(derived.has('Person')).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `cd platform/ui && npx vitest run server/lib/top-level-labels.test.ts`
+Expected: FAIL — `getTopLevelLabelAllowlist` is not exported / module not found.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ts
+// platform/ui/server/lib/top-level-labels.ts
+/**
+ * Server-side derivation of the /graph top-level chip allowlist from the
+ * per-vertical ontology.
+ *
+ * The allowlist is the union of two sources:
+ *   1. The `Neo4j Label` column of every `## Top-level node types` table in
+ *      `plugins/memory/references/schema-*.md`. Today only schema-construction
+ *      and schema-estate-agent carry that section; more arrive as verticals
+ *      gain one.
+ *   2. `STATIC_TOP_LEVEL_LABELS` — base-schema infra (schema-base.md has no
+ *      top-level section; its Node Types table mixes in child types) plus any
+ *      vertical whose schema has no top-level section yet.
+ *
+ * No namespace filter: every row contributes its label, so transport labels
+ * like WhatsAppGroup (cdm:Channel) stay chips. This differs from the account
+ * file-schema generator, which excludes non-schema: rows because a channel
+ * has no file bucket. A channel is still a legitimate operator-entry graph node.
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+/**
+ * Top-level labels not (yet) sourced from a vertical `## Top-level node types`
+ * section. This set shrinks as verticals gain a top-level section; each such
+ * change moves its labels from here into the derived union.
+ */
+export const STATIC_TOP_LEVEL_LABELS: ReadonlySet<string> = Object.freeze(
+  new Set([
+    // Base-schema infra (schema-base.md has no top-level section).
+    'LocalBusiness',
+    'Service',
+    'PriceSpecification',
+    'OpeningHoursSpecification',
+    'Organization',
+    'Person',
+    'UserProfile',
+    'Preference',
+    'AdminUser',
+    'AccessGrant',
+    'KnowledgeDocument',
+    'DigitalDocument',
+    'CreativeWork',
+    'Question',
+    'FAQPage',
+    'DefinedTerm',
+    'Review',
+    'ImageObject',
+    'Invoice',
+    'Task',
+    'Project',
+    'Event',
+    'Workflow',
+    'Email',
+    'EmailAccount',
+    'Agent',
+    // Knowledge-work vertical: schema-knowledge-work.md has no top-level
+    // section yet.
+    'Objective',
+    'KeyResult',
+    'Decision',
+    'Risk',
+    'Source',
+    'Finding',
+    'Hypothesis',
+  ]),
+) as ReadonlySet<string>
+
+/**
+ * Split a pipe-delimited markdown row into trimmed cells, honouring backtick
+ * code-spans so a `|` inside `` `A|B` `` does not split the row. Strips the
+ * optional leading/trailing pipes.
+ */
+function splitPipeRow(row: string): string[] {
+  let trimmed = row.trim()
+  if (trimmed.startsWith('|')) trimmed = trimmed.slice(1)
+  if (trimmed.endsWith('|')) trimmed = trimmed.slice(0, -1)
+  const cells: string[] = []
+  let inBacktick = false
+  let start = 0
+  for (let i = 0; i < trimmed.length; i++) {
+    const ch = trimmed[i]
+    if (ch === '`') inBacktick = !inBacktick
+    else if (ch === '|' && !inBacktick) {
+      cells.push(trimmed.slice(start, i).trim())
+      start = i + 1
+    }
+  }
+  cells.push(trimmed.slice(start).trim())
+  return cells
+}
+
+const stripBackticks = (s: string): string => s.replace(/`/g, '').trim()
+
+/**
+ * Extract the `Neo4j Label` column of the first pipe-table beneath a
+ * `## Top-level node types` heading. Returns [] when the file has no such
+ * section. The heading is matched by case-insensitive prefix so the
+ * `(operator-entry, natural key)` suffix is tolerated; parsing stops at the
+ * next `## ` heading.
+ */
+function parseTopLevelLabels(content: string): string[] {
+  const lines = content.split(/\r?\n/)
+  let i = 0
+  // Find the heading.
+  while (i < lines.length) {
+    const l = lines[i]
+    if (l.startsWith('## ') && l.toLowerCase().includes('top-level node types')) break
+    i++
+  }
+  if (i >= lines.length) return []
+  i++
+  // Find the header row of the first table before the next `## `.
+  for (; i < lines.length - 1; i++) {
+    const line = lines[i]
+    if (line.startsWith('## ')) return []
+    if (!line.includes('|')) continue
+    const sep = lines[i + 1]
+    if (!/^\s*\|?[\s:|-]+\|?\s*$/.test(sep) || !sep.includes('-')) continue
+    const headers = splitPipeRow(line)
+    const labelCol = headers.findIndex((h) => h.toLowerCase() === 'neo4j label')
+    if (labelCol === -1) return []
+    const out: string[] = []
+    let j = i + 2
+    for (; j < lines.length; j++) {
+      const row = lines[j]
+      if (!row.trim() || !row.includes('|')) break
+      const cells = splitPipeRow(row)
+      const label = stripBackticks(cells[labelCol] ?? '')
+      if (label) out.push(label)
+    }
+    return out
+  }
+  return []
+}
+
+function resolveReferencesDir(): string {
+  // Production: MAXY_PLATFORM_ROOT is `<install>/platform`, and the schema
+  // references live at `<platform>/plugins/memory/references` (same root
+  // schema-loader.ts resolves brand.json against).
+  if (process.env.MAXY_PLATFORM_ROOT) {
+    return join(process.env.MAXY_PLATFORM_ROOT, 'plugins', 'memory', 'references')
+  }
+  // Dev fallback (env unset, unbundled): three hops up from this source file,
+  // server/lib -> server -> ui -> platform, then plugins/memory/references.
+  return resolve(import.meta.dirname, '../../../plugins/memory/references')
+}
+
+let cached: ReadonlySet<string> | null = null
+
+/**
+ * The /graph top-level chip allowlist, derived from the ontology. Cached at
+ * module scope because schema files are static per install. An injected
+ * `referencesDir` (tests) bypasses the cache and does not populate it.
+ */
+export function getTopLevelLabelAllowlist(
+  opts: { referencesDir?: string } = {},
+): ReadonlySet<string> {
+  if (!opts.referencesDir && cached) return cached
+
+  const referencesDir = opts.referencesDir ?? resolveReferencesDir()
+  const fileNames = readdirSync(referencesDir)
+    .filter((f) => f.startsWith('schema-') && f.endsWith('.md'))
+    .sort()
+
+  const derived = new Set<string>()
+  const contributingFiles: string[] = []
+  for (const fileName of fileNames) {
+    const content = readFileSync(join(referencesDir, fileName), 'utf-8')
+    const labels = parseTopLevelLabels(content)
+    if (labels.length > 0) contributingFiles.push(fileName)
+    for (const label of labels) derived.add(label)
+  }
+
+  const derivedCount = derived.size
+  for (const label of STATIC_TOP_LEVEL_LABELS) derived.add(label)
+
+  const result = Object.freeze(derived) as ReadonlySet<string>
+  process.stderr.write(
+    `[graph-page] op=top-level-labels source=ontology count=${derived.size} ` +
+      `files=${contributingFiles.join('|') || 'none'} derived=${derivedCount} ` +
+      `static=${STATIC_TOP_LEVEL_LABELS.size}\n`,
+  )
+
+  if (!opts.referencesDir) cached = result
+  return result
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `cd platform/ui && npx vitest run server/lib/top-level-labels.test.ts`
+Expected: PASS — all four tests green. If the deep-equal test fails, the diff names the drifted label(s); reconcile `STATIC_TOP_LEVEL_LABELS` against `FILTER_TOP_LEVEL_LABELS` (do not weaken the assertion).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add platform/ui/server/lib/top-level-labels.ts platform/ui/server/lib/top-level-labels.test.ts
+git commit -m "feat: derive /graph top-level chip allowlist from vertical ontology (1624)"
+```
+
+---
+
+### Task 2: Point the three server routes at the derived allowlist
+
+**Files:**
+- Modify: `platform/ui/server/routes/admin/graph-labels-in-graph.ts`
+- Modify: `platform/ui/server/routes/admin/graph-subgraph.ts`
+- Modify: `platform/ui/server/routes/admin/graph-default-view.ts`
+
+**Interfaces:**
+- Consumes: `getTopLevelLabelAllowlist(): ReadonlySet<string>` from Task 1.
+- Produces: nothing new; behaviour of the three routes is unchanged because the derived set deep-equals `FILTER_TOP_LEVEL_LABELS`.
+
+- [ ] **Step 1: Confirm the existing route tests pass before the swap (baseline)**
+
+Run: `cd platform/ui && npx vitest run app/graph/__tests__/labels-in-graph.test.ts server/routes/__tests__/graph-default-topLevel.test.ts`
+Expected: PASS. This is the regression baseline the swap must preserve.
+
+- [ ] **Step 2: Swap the popover route**
+
+In `graph-labels-in-graph.ts`, change the import block
+
+```ts
+import {
+  FILTER_TOP_LEVEL_LABELS,
+  AGENT_ACTION_LABELS,
+} from '../../../app/lib/graph-labels'
+```
+
+to
+
+```ts
+import { AGENT_ACTION_LABELS } from '../../../app/lib/graph-labels'
+import { getTopLevelLabelAllowlist } from '../../lib/top-level-labels'
+```
+
+and change the allowlist construction (currently `new Set<string>(FILTER_TOP_LEVEL_LABELS)`)
+
+```ts
+    const allowedSet = new Set<string>(getTopLevelLabelAllowlist())
+    if (includeAgentActions) {
+      for (const label of AGENT_ACTION_LABELS) allowedSet.add(label)
+    }
+```
+
+- [ ] **Step 3: Swap the default-view fetch route**
+
+In `graph-subgraph.ts`, remove `FILTER_TOP_LEVEL_LABELS` from the `../../../app/lib/graph-labels` import (keep `HIDDEN_BY_DEFAULT_LABELS` and any others it imports), add `import { getTopLevelLabelAllowlist } from '../../lib/top-level-labels'`, and change line ~280
+
+```ts
+  const labels = [...getTopLevelLabelAllowlist()].filter((l) => !HIDDEN_BY_DEFAULT_LABELS.has(l))
+```
+
+- [ ] **Step 4: Swap the eligibility route**
+
+In `graph-default-view.ts`, replace
+
+```ts
+import { FILTER_TOP_LEVEL_LABELS } from '../../../app/lib/graph-labels'
+```
+
+with
+
+```ts
+import { getTopLevelLabelAllowlist } from '../../lib/top-level-labels'
+```
+
+and change the eligibility check (line ~158)
+
+```ts
+    if (!getTopLevelLabelAllowlist().has(lbl)) {
+```
+
+Update the adjacent `reason` string to drop the parenthetical `(FILTER_TOP_LEVEL_LABELS)` naming so no internal set name leaks; keep the operator-facing text: `label "${lbl}" is not eligible for default view — outside the chip allowlist`.
+
+- [ ] **Step 5: Run the route tests to verify no behaviour change**
+
+Run: `cd platform/ui && npx vitest run app/graph/__tests__/labels-in-graph.test.ts server/routes/__tests__/graph-default-topLevel.test.ts`
+Expected: PASS — the derived set equals `FILTER_TOP_LEVEL_LABELS`, so every assertion still holds.
+
+- [ ] **Step 6: Typecheck the UI package**
+
+Run: `cd platform/ui && npx tsc --noEmit`
+Expected: no errors (no unused-import errors for the removed `FILTER_TOP_LEVEL_LABELS`).
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add platform/ui/server/routes/admin/graph-labels-in-graph.ts platform/ui/server/routes/admin/graph-subgraph.ts platform/ui/server/routes/admin/graph-default-view.ts
+git commit -m "refactor: three /graph server routes read the ontology-derived allowlist (1624)"
+```
+
+---
+
+### Task 3: Update the graph-labels doc comment and file the client follow-up
+
+**Files:**
+- Modify: `platform/ui/app/lib/graph-labels.ts` (comment only — the set stays for the client)
+- Create: `.tasks/NNNN-graph-searchhelpers-derive-top-level-from-ontology.md` (number assigned at land time from LANES)
+
+**Interfaces:**
+- Consumes: nothing. Documentation and task-tracking only.
+
+- [ ] **Step 1: Annotate `FILTER_TOP_LEVEL_LABELS` as the client-only mirror**
+
+Add a sentence to the `FILTER_TOP_LEVEL_LABELS` doc block in `graph-labels.ts` recording that the server routes now derive this set from the vertical ontology (`server/lib/top-level-labels.ts`), and that this constant remains only for the client `searchHelpers.ts`, which cannot read files. Do not change the set members.
+
+- [ ] **Step 2: Write the follow-up task file**
+
+Create the task file describing: plumb the ontology-derived allowlist to the client `app/data/searchHelpers.ts` so its `/data` search chip pre-filter stops reading the static `FILTER_TOP_LEVEL_LABELS`, closing the last second source. In scope: deliver the derived set to the client (via the `graph-labels-in-graph` response the page already fetches, or an equivalent). Out of scope: the server routes (done here). Include Testing and Observability sections per the `.tasks` format.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add platform/ui/app/lib/graph-labels.ts .tasks/NNNN-graph-searchhelpers-derive-top-level-from-ontology.md
+git commit -m "docs: mark FILTER_TOP_LEVEL_LABELS client-only; file searchHelpers follow-up (1624)"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- New module + derivation → Task 1. ✅
+- Three server routes switch → Task 2. ✅
+- Byte-identical baseline → Task 1 Step 1 deep-equal test + Task 2 route tests. ✅
+- No namespace filter (WhatsAppGroup) → Task 1 Step 1 cdm test + the real-dir deep-equal (which contains WhatsAppGroup). ✅
+- Base list explicit → `STATIC_TOP_LEVEL_LABELS` in Task 1. ✅
+- Observability line → Task 1 Step 3 `process.stderr.write`. ✅
+- Client follow-up filed → Task 3. ✅
+- Count-gating unchanged → cypher untouched in Task 2; asserted by the pre-existing route tests. ✅
+
+**Placeholder scan:** The only deferred value is the follow-up task number (`NNNN`), assigned from LANES at archive time per sprint protocol — not a code placeholder.
+
+**Type consistency:** `getTopLevelLabelAllowlist(opts?: { referencesDir?: string }): ReadonlySet<string>` is used identically in Task 1 (definition), Task 1 test, and all three Task 2 call sites. `STATIC_TOP_LEVEL_LABELS` is a `ReadonlySet<string>`. Call sites use `.has()` and spread, both valid on `ReadonlySet`.

package/payload/platform/docs/superpowers/specs/2026-07-13-account-schema-ontology-projection-design.md

@@ -0,0 +1,178 @@
+# Account file-schema as a real projection of the domain graph ontology — design
+
+Source task: `.tasks/1622-account-file-schema-does-not-mirror-the-domain-graph-ontology.md`.
+Prior design (the mechanism this extends): `2026-06-23-account-filesystem-schema-design.md`.
+
+## Problem
+
+The account data directory is specified to be a projection of the graph ontology,
+but the allowed top-level set is a hardcoded generic base
+(`platform/templates/account-schema/SCHEMA.md`: `projects`, `contacts`,
+`documents` plus tool-owned dirs). Domain entities that the businessType ontology
+declares top-level are never added. On SiteDesk the ontology
+(`platform/plugins/memory/references/schema-construction.md`) makes `:Job` the hub
+with `:Customer`/`:Site`/`:Quote`/`:Visit`/`:Asset` as first-class operator-entry
+node types, and the sidebar's SiteDesk primary container is `:Job`, yet the
+account `SCHEMA.md` lists no `jobs` bucket. So a produced quote is filed inside the
+pricing plugin's private `quoting/jobs/<jobId>/` workspace, disconnected from the
+`:Job`/`:Quote` graph nodes and invisible to the Jobs view.
+
+A second, internal inconsistency exists inside the sitedesk-job plugin: the
+`valuation` skill's `references/job-folder.md` already documents the job folder as
+the top-level `$ACCOUNT_DIR/jobs/{jobId}/`, a path the file-schema does not permit,
+so valuation's own filing is admissible only by accident. Making `jobs/` a real
+derived bucket fixes both the quotation gap and this latent valuation gap.
+
+## The single source (resolves the task's "Depends on")
+
+`platform/plugins/memory/mcp/src/lib/schema-loader.ts` already machine-parses the
+schema markdown entity tables (each recognised by a `Neo4j Label` +
+`Required Properties` header pair). `brand.json#vertical` already names which
+`schema-<vertical>.md` applies (SiteDesk = `schema-construction`). Therefore
+`schema-<vertical>.md` is the single authoritative ontology, and the file-schema
+generator becomes a second reader of the same file. The graph loader itself does
+not change: it already reads these files. "The ontology" is one list, read by both
+the loader (for validation) and the generator (for top-level bucket derivation).
+
+`graph-labels.ts` `FILTER_TOP_LEVEL_LABELS` (the `/graph` UI chip allowlist) stays
+a separate concern this sprint. Single-sourcing it from the same per-vertical
+source is filed as a follow-up, not built here.
+
+## What ships
+
+### A. File-schema derives domain buckets from the vertical ontology
+
+**Convention for "top-level".** A label is a derived operator-entity bucket iff it
+appears as a row in the entity table under the heading
+`## Top-level node types (operator-entry, natural key)` in `schema-<vertical>.md`
+**and** its `Schema.org Type` column is a `schema:`-namespaced type. The
+`schema:`-namespace test deterministically excludes transport labels
+(`WhatsAppGroup` carries `cdm:Channel`) with no hardcoded skip-list. A vertical
+whose schema file carries no such heading contributes no domain buckets (generic
+base only) and is surfaced by the reconcile check (below).
+
+**Label to directory name.** kebab-case-plural of the label: camelCase word
+boundaries split on case, joined with `-`, lowercased, with a trailing `s`
+appended (or `y` becomes `ies`). Examples: `Job` to `jobs`, `Customer` to
+`customers`, `Quote` to `quotes`, `Asset` to `assets`, `Visit` to `visits`,
+`Part` to `parts`, `PurchaseOrder` to `purchase-orders`, `PpmContract` to
+`ppm-contracts`, `InboundInvoice` to `inbound-invoices`. One collision
+special-case: `Site` maps to `customer-sites`, so the tool-owned `sites/`
+published-tree bucket is untouched. The special-case is a single explicit entry in
+a `LABEL_DIR_OVERRIDES` map keyed by label; every other label uses the mechanical
+rule.
+
+**Generator.** `platform/scripts/lib/account-schema-owned-dirs.py` gains a
+`resolve_domain_buckets(project_dir)` beside the existing `resolve()` (plugin
+owned-dirs). It reads `brand.json#vertical`, opens
+`<project_dir>/plugins/memory/references/<vertical>.md`, extracts the top-level
+labels per the convention above, maps each to a dir, and returns
+`[{dir, label}, ...]` in table order. `merge()` unions these dirs into the
+`allowed-top-level` fenced block (same insertion path as owned-dirs) and writes a
+documented region between `<!-- ontology-buckets:start -->` and
+`<!-- ontology-buckets:end -->` markers, listing each bucket and its source label.
+The region is regenerated wholesale on every merge (idempotent), exactly like the
+existing plugin-owned region.
+
+**Provision.** No new call site. `merge_owned_dirs_into_schema` (in
+`account-schema-owned-dirs.sh`, already called by `provision-account-dir.sh` and
+`setup-account.sh`) now emits domain buckets as well as owned-dirs. Empty domain
+directories are **not** pre-created on provision. A fresh account has no jobs yet;
+the directory is created on first write, the same as any tool-owned dir. Only the
+allowed set and the `SCHEMA.md` region change at provision time.
+
+**Guard.** `platform/plugins/admin/hooks/fs-schema-guard.sh` needs no logic change.
+It already reads the account's `SCHEMA.md` allowed block and admits any first
+segment in that set at any depth except the three flat operator-data buckets
+(`projects`, `contacts`, `documents`). A domain bucket such as `jobs/` is therefore
+admitted at any depth, which is correct for the `jobs/<jobId>/Quotations/...`
+subtree the ontology's own filesystem projection describes. The derived buckets
+reach the guard through the regenerated allowed block.
+
+### B. Quotation reifies the Job/Quote/QuoteLine chain and files under the Job
+
+With `jobs/` a real bucket, the quotation apply-path is brought to parity with
+`valuation`'s job-setup (which already creates/updates `:Job` and `:Quote` and
+seeds `:QuoteLine`s on the quote). After the engine prices the job and
+`quote-render`'s fail-closed gates pass, the apply-path:
+
+1. **Reifies** `:Job-[:HAS_QUOTE]->:Quote-[:HAS_LINE]->:QuoteLine`, idempotent on
+   the natural keys the construction ontology defines (`:Job` on
+   `(accountId, jobId)`, `:Quote` on `(accountId, ref)`, `:QuoteLine` on
+   `(accountId, jobId, trade, description)`), via the same graph-write path
+   `valuation` uses. The exact write surface (memory tools vs the
+   `database-operator` specialist) is pinned in the plan by reading how
+   `valuation`'s job-setup writes today, so the two paths stay identical.
+2. **Files** the produced quote documents under the Job bucket
+   (`jobs/<jobId>/Quotations/...`, the operator-facing location valuation's
+   `job-folder.md` already documents), not orphaned in `quoting/jobs/<jobId>/`.
+   The `quoting/` engine workspace (`engine.mjs`, `method.json`, `render.mjs`, and
+   per-job figures) stays tool-owned. What changes is `quote-render`'s
+   filing-scope for the operator-facing result and the graph binding.
+3. **Emits** `[quote-render] op=quote-reify jobId=<id> quoteRef=<ref> lines=<n>` on
+   the graph write, a post-condition breadcrumb. A quote that renders documents but
+   writes no `:Quote` node is then immediately visible in the log.
+
+The schema-free pricing-method capture (item catalogue, rates, roll-up) is
+untouched. Only the output's placement and its entity binding are in scope.
+
+### C. estate-agent schema reorganisation (proves derivation is not hardcoded)
+
+`schema-estate-agent.md` currently holds one mixed `## Additional Node Types` table
+(hub `Property` plus its children `Listing`, `ImageObject`, `Viewing`, `Applicant`,
+`Offer`). It is reorganised into a `## Top-level node types (operator-entry,
+natural key)` table and a `## Child node types` table, with no row duplication, so
+`schema-loader` sees the same union of labels it sees today (it already parses
+construction's two-table shape). Top-level for estate-agent: `Property` (the
+obligatory hub) plus the operator-entry entities the vertical's prose names
+(`Listing`, `Viewing`, `Offer`). `ImageObject` is a child of `Listing` (reached
+through its parent, as construction places `QuoteLine`); `Applicant` is a Person
+extension (base `:Person` plus applicant properties, the same additional-label
+pattern construction uses for `Engineer`/`Supplier`), so neither is a top-level
+bucket. The exact top-level/child split for estate-agent is finalised during
+implementation by reading the whole file, but the two `schema:`-namespaced sets
+above are the intent. The result: a construction account derives `jobs`/`customers`/...
+and an estate-agent account derives `properties`/`listings`/`viewings`/`offers`
+from the same generator, proving the set is derived, not hardcoded.
+
+## Testing
+
+- `platform/scripts/__tests__/account-schema-owned-dirs.test.sh`: for a
+  construction brand, the merged allowed set contains `jobs`, `customers`,
+  `customer-sites`, `assets`, `visits`, `quotes` (and the rest), and does **not**
+  collide with the tool-owned `sites`. For an estate-agent brand it contains
+  `properties`, `listings`, `viewings`, `offers` and none of SiteDesk's buckets. A
+  vertical with no top-level heading yields no domain buckets (generic base
+  intact). `reconcile` reports every top-level label and whether its bucket is
+  present.
+- `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`: a write under
+  `jobs/<jobId>/Quotations/q.pdf` is admitted (domain bucket, any depth); an
+  undeclared top-level segment is still blocked; the three flat buckets keep their
+  over-deep block.
+- Cardinal repro (device-side, per the Pi-signal verification step): producing a
+  quote files the documents under the Job and the graph shows
+  `:Job-[:HAS_QUOTE]->:Quote-[:HAS_LINE]->:QuoteLine`; the quote appears in the
+  sidebar Jobs view. What is unit-testable locally is the derivation, the guard
+  admission, and the presence of the reify call and its breadcrumb.
+
+## Observability
+
+- `account-schema-owned-dirs.py reconcile` is extended into a standing check that
+  reports, per account, every top-level ontology entity **missing** a file-schema
+  bucket, so a re-divergence surfaces without waiting for a mis-filed artifact.
+- `[quote-render] op=quote-reify jobId= quoteRef= lines=` on quote production
+  confirms the graph write occurred.
+
+## Out of scope (each a filed follow-up, no prose-only deferral)
+
+- Normalising the remaining vertical schema files (`schema-retail`,
+  `schema-logistics`, `schema-hospitality`, `schema-food-beverage`,
+  `schema-professional-services`, `schema-trades`, `schema-creator`,
+  `schema-knowledge-work`) to carry the top-level heading. Until done they fall
+  back to the generic base and the reconcile check flags them. New task.
+- Single-sourcing `graph-labels.ts` `FILTER_TOP_LEVEL_LABELS` from the same
+  per-vertical ontology source. New task.
+- Backfilling existing `quoting/jobs/<jobId>/` figures folders for
+  already-produced quotes (the source task already defers this).
+- Any change to the graph schema, the `schema-loader` validation path, or the
+  `fs-schema-guard` decision logic beyond consuming the derived set.