@rubytech/create-maxy-code 0.1.485 → 0.1.487

package/payload/platform/plugins/admin/hooks/fs-schema-guard-bash-post.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# fs-schema-guard-bash-post — PostToolUse Bash stray-folder detection.
+#
+# The other half of the Bash-channel net (see fs-schema-guard-bash-pre.sh). After
+# a Bash command runs, this hook re-lists the account root, parses the account's
+# allowed-top-level set, and flags entries that are present NOW, absent from the
+# pre-snapshot, and not allowed — the strays THIS command created. For each it
+# emits exit 2 with a schema-citing message so the agent self-corrects within the
+# same turn.
+#
+# No filesystem mutation: PostToolUse runs after the command executed, so it
+# cannot prevent the mkdir, and auto-deleting a just-created folder risks
+# destroying legitimate in-flight work (auto-repair was rejected). The standing
+# reconcile (account-dir-schema-reconcile.ts) is the net for anything the agent
+# ignores or that predates the hook.
+#
+# Diffing against the pre-snapshot (not flagging every non-allowed entry) is what
+# keeps the hook from firing on the legacy backlog on every unrelated Bash call.
+#
+# Exit codes: 0 = allow, 2 = feedback to the agent (stderr shown). Fail open
+# (exit 0) when the snapshot is missing or the allowed set is empty. Every block
+# logs: [fs-guard-bash] stray path=<name> reason=<top-level|bad-name>
+# No task numbers / internal refs in any operator-visible string.
+
+set -uo pipefail
+
+# No stdin envelope (tty) — cannot inspect. Fail open (post hooks never block on
+# an un-inspectable call; a false block on every terminal-run Bash is worse than
+# a missed stray the reconcile still catches).
+[ -t 0 ] && exit 0
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+field() {
+  printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('$1', '') or '')
+except Exception:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+TOOL_NAME=$(field tool_name)
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+SESSION_ID=$(field session_id)
+[ -z "$SESSION_ID" ] && exit 0
+
+if [ -n "${FS_GUARD_BASH_TMPDIR:-}" ]; then
+  TMP_DIR="$FS_GUARD_BASH_TMPDIR"
+else
+  TMP_DIR="${TMPDIR:-${TMP:-${TEMP:-/tmp}}}"
+  TMP_DIR="${TMP_DIR%/}"
+fi
+SID_SAN=$(printf '%s' "$SESSION_ID" | sed 's/[^A-Za-z0-9_-]/_/g')
+SNAP="$TMP_DIR/maxy-fsguard-snapshot-${SID_SAN}.txt"
+
+# Missing pre-snapshot -> fail open (the pre hook could not run or failed open).
+[ -f "$SNAP" ] || exit 0
+
+ACCOUNT_DIR="$PWD"
+
+# Parse the allowed top-level set from the account's seeded SCHEMA.md — the same
+# awk extraction fs-schema-guard.sh uses. Empty/absent -> fail open.
+ALLOWED=""
+if [ -f "$ACCOUNT_DIR/SCHEMA.md" ]; then
+  ALLOWED=$(awk '/^```allowed-top-level$/{f=1;next} /^```$/{f=0} f' "$ACCOUNT_DIR/SCHEMA.md")
+fi
+[ -z "$ALLOWED" ] && exit 0
+
+# Compute this command's findings, each tagged `reason<TAB>name`:
+#   top-level : an account-root entry present now, absent from the pre-snapshot,
+#               not in the allowed set (the original stray check).
+#   bad-name  : an immediate child of an operator-data bucket (projects/contacts/
+#               documents) that is NEW this command whose name breaks the
+#               convention. A bucket absent from the pre-snapshot is new, so all
+#               its children are this command's doing; flagging them cannot
+#               re-spam the legacy backlog, which lives only in pre-existing
+#               buckets. Bad names under a pre-existing bucket are the standing
+#               reconcile's job (it can distinguish backlog from fresh; this hook
+#               cannot, with a top-level-only snapshot). python3 does the set
+#               arithmetic and regex (names may contain spaces).
+FINDINGS=$(ACCOUNT_DIR="$ACCOUNT_DIR" SNAP="$SNAP" ALLOWED="$ALLOWED" python3 -c '
+import os, sys, re
+acct = os.environ["ACCOUNT_DIR"]
+try:
+    now = set(os.listdir(acct))
+except Exception:
+    sys.exit(1)
+with open(os.environ["SNAP"]) as f:
+    before = set(l for l in f.read().split("\n") if l != "")
+allowed = set(l.strip() for l in os.environ["ALLOWED"].split("\n") if l.strip())
+
+out = []
+for name in sorted((now - before) - allowed):
+    out.append("top-level\t" + name)
+
+folder_re = re.compile(r"^[a-z0-9-]+\Z")
+file_re = re.compile(r"^[a-z0-9-]+(\.[a-z0-9-]+)*\Z")
+for bucket in ("projects", "contacts", "documents"):
+    if bucket in before or bucket not in now:
+        continue  # pre-existing bucket, or not created this command
+    bpath = os.path.join(acct, bucket)
+    try:
+        children = os.listdir(bpath)
+    except Exception:
+        continue
+    for child in sorted(children):
+        if child.startswith("."):
+            continue  # dot-prefixed entries are skipped at every level
+        rx = folder_re if os.path.isdir(os.path.join(bpath, child)) else file_re
+        if not rx.match(child):
+            out.append("bad-name\t" + child)
+
+sys.stdout.write("\n".join(out))
+' 2>/dev/null) || exit 0
+
+[ -z "$FINDINGS" ] && exit 0
+
+# One log line per finding, then a schema-citing feedback block per reason seen.
+# exit 2 feeds stderr back to the agent.
+TOPLEVEL=""
+BADNAME=""
+{
+  while IFS=$'\t' read -r reason name; do
+    [ -z "$reason" ] && continue
+    case "$reason" in
+      top-level) echo "[fs-guard-bash] stray path=$name reason=top-level"; TOPLEVEL="$TOPLEVEL $name" ;;
+      bad-name)  echo "[fs-guard-bash] stray path=$name reason=bad-name";  BADNAME="$BADNAME $name" ;;
+    esac
+  done <<< "$FINDINGS"
+  if [ -n "$TOPLEVEL" ]; then
+    echo "Blocked: this Bash command created top-level entries that are not allowed in this account's data directory:$TOPLEVEL. The layout is fixed by SCHEMA.md — only the entries listed there are permitted at the top level. Relocate this content under projects/, contacts/, or documents/, and route any reorganisation through the data-manager specialist."
+  fi
+  if [ -n "$BADNAME" ]; then
+    echo "Blocked: this Bash command created names that break the account's naming rule:$BADNAME. Folder and file names under projects/, contacts/, and documents/ use lowercase letters, digits, and hyphens only, with a lowercase file extension. Rename them, or route a reorganisation through the data-manager specialist."
+  fi
+} >&2
+exit 2

package/payload/platform/plugins/admin/hooks/fs-schema-guard-bash-pre.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# fs-schema-guard-bash-pre — PreToolUse Bash account-root snapshot.
+#
+# The Write/Edit/NotebookEdit path guard (fs-schema-guard.sh) does not see Bash:
+# a folder created through mkdir/mv/cp/redirect bypasses it entirely. This hook
+# is half of the Bash-channel net: it records the account root's immediate
+# top-level entry names BEFORE the Bash command runs, so the PostToolUse twin
+# (fs-schema-guard-bash-post.sh) can diff and flag only the strays THIS command
+# newly created — never the pre-existing legacy backlog.
+#
+# The hook inspects account-root STATE, never the command string (command-string
+# parsing was rejected as brittle and evadable). $PWD is the account dir.
+#
+# Fail open on every error (no session id, no python3, unlistable dir, unwritable
+# tmp): a snapshot that cannot be taken must not block the command. exit 0 always
+# — a PreToolUse snapshot never blocks; blocking is the post hook's job.
+
+set -uo pipefail
+
+# No stdin envelope (tty) — nothing to snapshot. Fail open.
+[ -t 0 ] && exit 0
+INPUT=$(cat)
+[ -z "$INPUT" ] && exit 0
+
+field() {
+  printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('$1', '') or '')
+except Exception:
+    print('')
+" 2>/dev/null || echo ""
+}
+
+TOOL_NAME=$(field tool_name)
+[ "$TOOL_NAME" = "Bash" ] || exit 0
+
+SESSION_ID=$(field session_id)
+[ -z "$SESSION_ID" ] && exit 0
+
+# Resolve the tmpdir the same way the manager's Node process does (libuv
+# uv_os_tmpdir): TMPDIR, then TMP, then TEMP, then /tmp; strip a trailing slash.
+# FS_GUARD_BASH_TMPDIR overrides for tests only — never set in production.
+if [ -n "${FS_GUARD_BASH_TMPDIR:-}" ]; then
+  TMP_DIR="$FS_GUARD_BASH_TMPDIR"
+else
+  TMP_DIR="${TMPDIR:-${TMP:-${TEMP:-/tmp}}}"
+  TMP_DIR="${TMP_DIR%/}"
+fi
+SID_SAN=$(printf '%s' "$SESSION_ID" | sed 's/[^A-Za-z0-9_-]/_/g')
+SNAP="$TMP_DIR/maxy-fsguard-snapshot-${SID_SAN}.txt"
+
+# List the account root's immediate top-level entry names, one per line. python3
+# os.listdir gives names only (no recursion). Any failure -> fail open.
+ACCOUNT_DIR="$PWD" python3 -c '
+import os, sys
+acct = os.environ["ACCOUNT_DIR"]
+try:
+    names = os.listdir(acct)
+except Exception:
+    sys.exit(1)
+sys.stdout.write("\n".join(names))
+' > "$SNAP" 2>/dev/null || { rm -f "$SNAP" 2>/dev/null; exit 0; }
+
+exit 0

package/payload/platform/plugins/admin/hooks/fs-schema-guard.sh

@@ -14,7 +14,7 @@
 #
 # Exit codes: 0 = allow, 2 = block (stderr shown to the agent). Fail closed when
 # the tool call cannot be inspected (tty or empty stdin). Every block logs
-#   [fs-guard] blocked path=<rel> reason=<top-level|over-deep>
+#   [fs-guard] blocked path=<rel> reason=<top-level|over-deep|bad-name>
 # No task numbers / internal refs in any operator-visible string.
 
 set -uo pipefail
@@ -105,4 +105,36 @@ case "$SEG0" in
     ;;
 esac
 
+# Name-convention check for the operator-data buckets, after top-level and depth
+# pass. The operator-authored segments carry a character rule: folders are
+# [a-z0-9-]; the write target (last segment, always a file) is lowercase
+# dot-segments so a lowercase extension is allowed. The bucket segment (top-level
+# rule) and dot-prefixed entries (skipped at every level system-wide) are exempt.
+# Space-/case-/underscore-bearing names break shell paths, data-portal URL
+# minting, and case-sensitive matching.
+case "$SEG0" in
+  projects|contacts|documents)
+    BADSEG=$(REL="$REL" python3 -c '
+import os, re
+segs = os.environ["REL"].split("/")
+folder_re = re.compile(r"^[a-z0-9-]+\Z")
+file_re = re.compile(r"^[a-z0-9-]+(\.[a-z0-9-]+)*\Z")
+bad = ""
+for i, s in enumerate(segs):
+    if i == 0 or s.startswith("."):
+        continue  # bucket segment (top-level rule), or a dot-prefixed entry
+    ok = file_re.match(s) if i == len(segs) - 1 else folder_re.match(s)
+    if not ok:
+        bad = s
+        break
+print(bad)
+' 2>/dev/null || echo "")
+    if [ -n "$BADSEG" ]; then
+      echo "[fs-guard] blocked path=$REL reason=bad-name" >&2
+      echo "Blocked: '$BADSEG' is not a valid name in this account's data directory. Folder and file names under projects/, contacts/, and documents/ use lowercase letters, digits, and hyphens only, with a lowercase file extension. Rename it to fit, or route a reorganisation through the data-manager specialist." >&2
+      exit 2
+    fi
+    ;;
+esac
+
 exit 0

package/payload/platform/plugins/admin/skills/professional-document/SKILL.md

@@ -145,7 +145,7 @@ Emit `[professional-document] render → a4-print-documents`.
 
 ### 8. Ask the operator for the output path
 
-Before saving the PDF, ask the operator where they want it saved. The operator names the path (file name and directory). Do not invent the path. The path the operator names is where the PDF is written and what the observability line records.
+Before saving the PDF, ask the operator where they want it saved. When the document is a deliverable for a known Job (its scope of works, budget estimate, warranty, valuation, or completion certificate), propose `jobs/<jobNumber>/<file>` as the default path, where `<jobNumber>` is the job's canonical numeric id, the same key the quote path uses at `quoting/jobs/<jobId>/`. If no `jobs/<jobNumber>/` folder exists yet, it is created; `jobs/` is an ontology entity bucket, so the deliverable sits directly under the job's folder, not in `output/`. For a document tied to no Job record, ask without proposing a default. The operator can always confirm the default or name a different path, and the path the operator confirms is where the PDF is written and what the observability line records. Do not write to a path the operator has not confirmed.
 
 ### 9. Save the PDF
 
@@ -155,13 +155,13 @@ Emit `[professional-document] pdf-saved path=<operator-named-path> bytes=<n>`.
 
 ### 10. Deliver
 
-The PDF you saved is the deliverable. How you hand it over depends on the surface this turn arrived on. On a message channel (web chat, WhatsApp, Telegram), call `SendUserFile` with the saved path and the platform forwards the PDF to that conversation as a real attachment. On the admin dashboard, a path under `accounts/<accountId>/output/` appears in the Artefacts panel (downloadable) and is reachable on the file share. Either way, state the complete path in your reply, never a vague pointer. See the `file-presentation` skill for the wording.
+The PDF you saved is the deliverable. How you hand it over depends on the surface this turn arrived on. On a message channel (web chat, WhatsApp, Telegram), call `SendUserFile` with the saved path and the platform forwards the PDF to that conversation as a real attachment. On the admin dashboard, any saved path under `accounts/<accountId>/` (a job's `jobs/<jobNumber>/` folder, `output/`, or elsewhere in the account tree) appears in the Artefacts panel (downloadable) and is reachable on the file share. Either way, state the complete path in your reply, never a vague pointer. See the `file-presentation` skill for the wording.
 
 ## Doctrine
 
 - **Compose, do not duplicate.** `a4-print-documents` owns the print-CSS rules; this skill loads it and follows it. `prose-craft` owns sentence-level review; this skill invokes it when present. `memory-search` owns graph reads; this skill calls it for grounding. The seam is "this skill is the workflow; the loaded skills carry the rules."
 - **Refuse before composing.** Every brief runs through the refusal taxonomy first. A skill that drafts something it should have refused is a routing defect, not a quality issue.
-- **Operator-named output path.** The skill never invents the path. The operator names where the PDF lands. This matches how `investor-data-room` and the property composers work.
+- **Operator-named output path.** For a deliverable tied to a known Job, the skill proposes that job's `jobs/<jobNumber>/` entity folder as the default; for anything else it proposes no path. The operator confirms the default or names a different path, and the skill never writes to a path the operator has not confirmed. This matches how `investor-data-room` and the property composers work.
 - **Approve the outline before drafting.** Long documents whose structure is wrong cost more to re-draft than they cost to re-outline. The approval turn is cheap; the wasted draft is expensive.
 - **No invented facts.** Every quantitative or named claim grounds in `memory-search` or a `research-assistant` brief-back. If the graph does not carry the fact and the operator has not asked for research, draft a one-line gap statement in place ("[GAP: <description>]") and surface it in the outline-approval turn.
 - **No live web research from this skill.** If a fact is missing, ask the admin agent to dispatch `research-assistant`. This skill does not call `WebFetch` or `WebSearch` directly.

package/payload/platform/plugins/cloudflare/PLUGIN.md

@@ -71,16 +71,18 @@ The setup-done claim only fires when `curl -I https://<hostname>` issued from ou
 
 ## Data-portal folder index
 
-The portal shows a sub-account's deliverable folders alongside what the client uploaded. Which folders those are is never a list in the code: it is derived per account from that account's own `SCHEMA.md` — the buckets in its `<!-- ontology-buckets -->` region plus `output`, intersected with its `allowed-top-level` block. A brand on a different vertical exposes different folders with no code change. `bin/schema-exposed-dirs.mjs` is the only place that decision is made.
+The portal shows a sub-account's deliverable folders alongside what the client uploaded. Which folders those are is never a list in the code: it is derived per account from that account's own `SCHEMA.md` — the buckets in its `<!-- ontology-buckets -->` region plus `output`, intersected with its `allowed-top-level` block. A brand on a different vertical exposes different folders with no code change. `bin/schema-exposed-dirs.mjs` is the only place that decision is made. An operator can add non-ontology folders (a workflow folder such as `inbound-invoices`) by listing them in `exposeFolders` in the account's `data-portal.json`; each must match `[A-Za-z0-9_-]+` and is never a system folder (`agents`, `secrets`, `specialists`, `state`, `memory`, `cache`, `logs`, `tmp`) or dot-prefixed. Those extras union on top of the schema-derived set and, unlike ontology buckets, are not intersected with `allowed-top-level`; empty or absent behaves as before.
 
 `bin/portal-index-push.mjs` walks those folders and full-replaces the account's rows in the portal's D1 `directory` table each cycle. Metadata only — names, sizes, times — so listing survives the device being offline, and a deleted or renamed file converges on the next cycle without a tombstone. The scheduling heartbeat runs it hourly for every account carrying a `data-portal.json`; it is also runnable standalone, which is how it stays operable while the heartbeat spawn path is unproven on a device.
 
 Opening a file reaches the install: the portal probes it, then mints an `/api/portal/fetch` link signed with the account's `PORTAL_FETCH_SECRET` and valid for five minutes. The install verifies the signature **and independently re-derives the exposed folder set**, so a correctly signed link for a non-exposed path is still refused. That second check is the security boundary, not the signature.
 
+Exposure is narrowed twice. The install re-derives the account's exposed set from `SCHEMA.md` on every request and refuses anything outside it, which is the account-isolation boundary. On top of that, a person's `people.folders` grant (written at enrolment, empty means the full set) narrows them to named top-level folders inside that set. The grant lives only in the portal's D1, so a portal compromise widens a person back to the account's exposed set and never beyond it. `op=list` carries `granted=<n|full>` and an out-of-grant download logs `op=fetch-through result=not-granted`, distinct from `result=absent`.
+
 What to watch, on the device:
 
 ```
-[portal-index] op=resolve account=<id> schemaPresent=<bool> allowed=<n> domainBuckets=<dirs|none> exposed=<dirs|none>
+[portal-index] op=resolve account=<id> schemaPresent=<bool> allowed=<n> domainBuckets=<dirs|none> extraFolders=<n> exposed=<dirs|none>
 [portal-index] op=replace account=<id> deleted=all inserted=<n>
 [portal-index] op=verify  account=<id> rowsAfter=<n> expected=<n>
 [portal-index] op=collision account=<id> dir=<dir> claimedBy=plugin-owned
@@ -88,7 +90,7 @@ What to watch, on the device:
 [portal-index] op=audit accounts=<n> stale=<n> never-ran=<n>
 ```
 
-`exposed=none` where deliverables exist means the schema was missing or carried no ontology region — not that the walk found nothing. `rowsAfter` disagreeing with `expected` is a half-applied replace. An `op=collision` line explains a folder that has silently vanished from the client's view, which nothing else would report. `op=exposed-changed` fires only on a delta, so it is rare and always worth reading; a `removed=` naming a populated bucket is the client-visible regression.
+`exposed=none` where deliverables exist means the schema was missing or carried no ontology region — not that the walk found nothing. `rowsAfter` disagreeing with `expected` is a half-applied replace. An `op=collision` line explains a folder that has silently vanished from the client's view, which nothing else would report. `op=exposed-changed` fires only on a delta, so it is rare and always worth reading; a `removed=` naming a populated bucket is the client-visible regression. `extraFolders=<n>` counts the folders the operator requested in `exposeFolders`; a non-zero `extraFolders` with none of those names in `exposed=` means the guard dropped every one.
 
 `op=audit` is the standing check, and it is the only one that speaks when the push does **not**. It runs in-process inside the heartbeat rather than as a spawn, and reads only local state, so it cannot be blinded by the same failure it is watching for. It fires hourly even when everything is healthy — an audit that goes quiet on success is indistinguishable from an audit that stopped running. `result=never-ran` on an account with a `data-portal.json` means no cycle has ever succeeded for it; `result=stale` with `ageMin` means cycles have stopped. Its input is written only after `op=verify`, so a stale entry means the push stopped succeeding rather than merely stopped logging.
 

package/payload/platform/plugins/cloudflare/bin/portal-enrol.mjs

@@ -71,6 +71,26 @@ if (!/^[A-Za-z0-9-]+$/.test(/** @type {string} */ (accountId))) {
   die('--account must match ^[A-Za-z0-9-]+$ — an account id, not a path')
 }
 
+// Optional per-person folder allowlist: comma-separated top-level names that
+// narrow what this person sees below the account's exposed set. Absent means
+// the full set. Each name is validated to the dir-segment charset, so a grant
+// can never carry a path separator, a comma inside a name, or a SQL quote: the
+// value goes into the statement as a plain comma-joined literal.
+const foldersArg = arg('--folders')
+let folders = ''
+if (foldersArg !== undefined) {
+  const names = foldersArg
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+  for (const n of names) {
+    if (!/^[A-Za-z0-9_-]+$/.test(n)) {
+      die(`--folders entry ${JSON.stringify(n)} must match ^[A-Za-z0-9_-]+$ — a folder name, not a path`)
+    }
+  }
+  folders = [...new Set(names)].join(',')
+}
+
 const saltBytes = new Uint8Array(16)
 crypto.getRandomValues(saltBytes)
 const saltHex = randomSaltHex(saltBytes)
@@ -98,9 +118,10 @@ const createdAt = new Date().toISOString()
 //
 // `accountId` IS in the DO UPDATE: re-enrolling someone against a different
 // sub-account has to move them, or they keep reading folders they no longer
-// belong to.
+// belong to. `folders` IS too, for the same reason: re-enrolment replaces the
+// grant, so a narrower or wider set on re-run takes effect rather than sticking.
 console.log(
-  `INSERT INTO people (ownerId, name, salt, hash, createdAt, accountId) VALUES ('${ownerId}', '${sqlName}', '${saltHex}', '${hash}', '${createdAt}', '${accountId}') ON CONFLICT(ownerId) DO UPDATE SET name=excluded.name, salt=excluded.salt, hash=excluded.hash, accountId=excluded.accountId;`,
+  `INSERT INTO people (ownerId, name, salt, hash, createdAt, accountId, folders) VALUES ('${ownerId}', '${sqlName}', '${saltHex}', '${hash}', '${createdAt}', '${accountId}', '${folders}') ON CONFLICT(ownerId) DO UPDATE SET name=excluded.name, salt=excluded.salt, hash=excluded.hash, accountId=excluded.accountId, folders=excluded.folders;`,
 )
 
 // stderr: everything for the human. Never stdout — see the note at the top.

package/payload/platform/plugins/cloudflare/bin/portal-index-push.mjs

@@ -42,6 +42,20 @@ function readEnvFile(path) {
   return out
 }
 
+/** Operator-named extra folders for an account, from its data-portal.json.
+ *  Absent file, absent key, or a non-array value all yield []. The resolver
+ *  applies the charset-and-system guard; this reader does not pre-filter, so the
+ *  `extraFolders=<n>` count reflects what the operator asked for.
+ *  @param {string} accountDir @returns {Promise<string[]>} */
+export async function readExposeFolders(accountDir) {
+  try {
+    const cfg = JSON.parse(await readFile(join(accountDir, 'data-portal.json'), 'utf8'))
+    return Array.isArray(cfg?.exposeFolders) ? cfg.exposeFolders.filter((f) => typeof f === 'string') : []
+  } catch {
+    return []
+  }
+}
+
 /**
  * Files under `exposed` dirs, at any depth. Dot-prefixed entries are skipped at
  * every level: `.uploads-tmp/` holds in-flight upload partials (files.ts:25) and
@@ -85,7 +99,7 @@ export async function walkExposed(accountDir, exposed) {
  * @param {{ accountDir: string, accountId: string, dbName: string,
  *           client: { query: (sql: string, params?: unknown[]) => Promise<Record<string, unknown>[]> },
  *           log: (line: string) => void, nowIso: string,
- *           previousExposed?: string[] }} opts
+ *           exposeFolders?: string[], previousExposed?: string[] }} opts
  * @returns {Promise<{ exposed: string[], rows: number, schemaPresent: boolean }>}
  */
 export async function pushAccount(opts) {
@@ -98,10 +112,15 @@ export async function pushAccount(opts) {
     schemaText = null
   }
 
-  const r = resolveExposedDirs(schemaText)
+  const exposeFolders = Array.isArray(opts.exposeFolders) ? opts.exposeFolders : []
+  const r = resolveExposedDirs(schemaText, exposeFolders)
+  // extraFolders is the REQUESTED count, not the accepted count: a non-zero
+  // extraFolders with none of those names in exposed= means the guard dropped
+  // every one, which is distinct from none configured (extraFolders=0).
   log(
     `${TAG} op=resolve account=${accountId} schemaPresent=${r.schemaPresent} allowed=${r.allowed.length} ` +
-      `domainBuckets=${r.domainBuckets.join(',') || 'none'} exposed=${r.exposed.join(',') || 'none'}`,
+      `domainBuckets=${r.domainBuckets.join(',') || 'none'} extraFolders=${exposeFolders.length} ` +
+      `exposed=${r.exposed.join(',') || 'none'}`,
   )
   // The generator gives a plugin-claimed dir to the plugin-owned region only
   // (account-schema-owned-dirs.py:287), so this is normally silent. When it is
@@ -212,10 +231,10 @@ function arg(flag) {
  * Every account carrying a data-portal.json has a portal. The file's presence is
  * the enrolment signal — there is no separate flag to keep in sync with it.
  * @param {string} accountsRoot
- * @returns {Promise<{accountDir: string, accountId: string, dbName: string}[]>}
+ * @returns {Promise<{accountDir: string, accountId: string, dbName: string, exposeFolders: string[]}[]>}
  */
 async function portalAccounts(accountsRoot) {
-  /** @type {{accountDir: string, accountId: string, dbName: string}[]} */ const out = []
+  /** @type {{accountDir: string, accountId: string, dbName: string, exposeFolders: string[]}[]} */ const out = []
   /** @type {string[]} */ let names
   try {
     names = await readdir(accountsRoot)
@@ -227,7 +246,10 @@ async function portalAccounts(accountsRoot) {
     try {
       const cfg = JSON.parse(await readFile(join(accountDir, 'data-portal.json'), 'utf8'))
       if (typeof cfg?.portalDbName === 'string' && cfg.portalDbName) {
-        out.push({ accountDir, accountId, dbName: cfg.portalDbName })
+        const exposeFolders = Array.isArray(cfg?.exposeFolders)
+          ? cfg.exposeFolders.filter((f) => typeof f === 'string')
+          : []
+        out.push({ accountDir, accountId, dbName: cfg.portalDbName, exposeFolders })
       } else {
         console.error(`${TAG} op=skip account=${accountId} reason=no-portalDbName`)
       }
@@ -292,7 +314,7 @@ async function main() {
     process.exit(1)
   }
 
-  /** @type {{accountDir: string, accountId: string, dbName: string}[]} */ let targets
+  /** @type {{accountDir: string, accountId: string, dbName: string, exposeFolders: string[]}[]} */ let targets
   if (process.argv.includes('--all-accounts')) {
     // Same derivation as the platform's own DATA_ROOT (data-path.ts:19), from
     // the PLATFORM_ROOT the heartbeat already passes.
@@ -307,7 +329,7 @@ async function main() {
       console.error(`${TAG} op=usage --account-dir <dir> --account <id> --db <name>`)
       process.exit(1)
     }
-    targets = [{ accountDir, accountId, dbName }]
+    targets = [{ accountDir, accountId, dbName, exposeFolders: await readExposeFolders(accountDir) }]
   }
 
   const state = readState(platformRoot)

package/payload/platform/plugins/cloudflare/bin/schema-exposed-dirs.mjs

@@ -21,6 +21,18 @@ const OWNED_END = '<!-- plugin-owned-dirs:end -->'
 /** The delivery convention, always exposed when the account allows it. */
 export const ALWAYS_EXPOSED = 'output'
 
+/** Folders that must never be named into exposure, even by an operator. The
+ *  dot-prefixed `.git`/`.claude` are already excluded by the charset guard
+ *  below. This is the not-system half of the extra-folder bound. */
+const SYSTEM_DIRS = new Set(['agents', 'secrets', 'specialists', 'state', 'memory', 'cache', 'logs', 'tmp'])
+
+/** An operator-named extra folder is accepted only as a single safe segment
+ *  (the same charset the per-person `--folders` grant enforces) and never a
+ *  system dir. This drops dot-prefixed names, slashes, and traversal such as
+ *  `jobs/../secrets`, which would otherwise let the push walk index files under
+ *  a system dir that the fetch route would refuse to serve. */
+const SAFE_FOLDER = /^[A-Za-z0-9_-]+$/
+
 /**
  * The generator writes the ontology region with an ASCII hyphen and the
  * plugin-owned region with an em dash (account-schema-owned-dirs.py:294 vs
@@ -53,10 +65,11 @@ function allowedBlockOrNull(text) {
 
 /**
  * @param {string | null} schemaText Contents of accounts/<id>/SCHEMA.md, or null when absent.
+ * @param {string[]} [exposeFolders] Operator-named extra top-level folders. Empty or absent = today.
  * @returns {{ schemaPresent: boolean, allowed: string[], domainBuckets: string[],
  *            pluginOwned: string[], collisions: string[], exposed: string[] }}
  */
-export function resolveExposedDirs(schemaText) {
+export function resolveExposedDirs(schemaText, exposeFolders = []) {
   const empty = {
     schemaPresent: false,
     allowed: /** @type {string[]} */ ([]),
@@ -97,7 +110,14 @@ export function resolveExposedDirs(schemaText) {
   const collisions = domainBuckets.filter((d) => pluginOwned.includes(d))
 
   const candidates = [ALWAYS_EXPOSED, ...domainBuckets.filter((d) => !collisions.includes(d))]
-  const exposed = [...new Set(candidates)].filter((d) => allowed.includes(d)).sort()
+  const ontologyExposed = [...new Set(candidates)].filter((d) => allowed.includes(d))
+  // Extras are unioned AFTER the ontology step and are deliberately NOT
+  // intersected with `allowed`: a workflow folder is legitimately outside the
+  // ontology set. The charset-plus-deny guard is the whole bound.
+  const extras = (Array.isArray(exposeFolders) ? exposeFolders : []).filter(
+    (f) => typeof f === 'string' && SAFE_FOLDER.test(f) && !SYSTEM_DIRS.has(f),
+  )
+  const exposed = [...new Set([...ontologyExposed, ...extras])].sort()
 
   return { schemaPresent: true, allowed, domainBuckets, pluginOwned, collisions, exposed }
 }

package/payload/platform/plugins/cloudflare/mcp/__tests__/authorize.test.ts

@@ -67,7 +67,7 @@ describe('sessions', () => {
   it('mints a session resolvable to its owner', async () => {
     const { db } = fakeDb()
     await mintSession(db, 'alice', 'sess-1', 1_000_000, PC)
-    expect(await resolveSession(db, 'sess-1', 1_000_000)).toEqual({ ownerId: 'alice', accountId: '' })
+    expect(await resolveSession(db, 'sess-1', 1_000_000)).toEqual({ ownerId: 'alice', accountId: '', folders: [] })
   })
 
   it('does not resolve an expired session', async () => {
@@ -97,7 +97,7 @@ describe('session revocation — the property the design claims', () => {
     // by construction, not by remembering to delete anything.
     const { db, peopleRows } = fakeDb()
     await mintSession(db, 'alice', 'sess-1', 1_000_000, PC)
-    expect(await resolveSession(db, 'sess-1', 1_000_000)).toEqual({ ownerId: 'alice', accountId: '' })
+    expect(await resolveSession(db, 'sess-1', 1_000_000)).toEqual({ ownerId: 'alice', accountId: '', folders: [] })
 
     peopleRows[0].hash = 'HASH-v2-rotated0' // operator re-runs enrolment
 

package/payload/platform/plugins/cloudflare/mcp/__tests__/portal-directory-listing.test.ts

@@ -9,7 +9,9 @@ const DIRECTORY = [
   { accountId: 'acc-b', relPath: 'output/secret.pdf', sizeBytes: 40, modifiedAt: '2026-07-20T13:00:00.000Z' },
 ]
 
-function makeEnv(sessions: Record<string, { ownerId: string; accountId: string }>) {
+function makeEnv(
+  sessions: Record<string, { ownerId: string; accountId: string; folders?: string }>,
+) {
   return {
     DB: {
       prepare(query: string) {
@@ -39,7 +41,7 @@ function makeEnv(sessions: Record<string, { ownerId: string; accountId: string }
   } as unknown as PortalEnv
 }
 
-const SESSIONS = { 'sess-a': { ownerId: 'alice', accountId: 'acc-a' } }
+const SESSIONS = { 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: '' } }
 type Entry = { name: string; kind: string; relPath: string; sizeBytes: number | null; modifiedAt: string | null }
 
 describe('entriesUnder', () => {
@@ -117,4 +119,49 @@ describe('processFiles directory listing', () => {
     expect(r.payload).toHaveProperty('files')
     expect(r.payload).toHaveProperty('entries')
   })
+
+  it('shows only granted top-level folders', async () => {
+    const env = makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: 'quotes' } })
+    const r = await processFiles('sess-a', env, () => {}, 0, '')
+    expect((r.payload.entries as Entry[]).map((e) => e.name)).toEqual(['quotes'])
+  })
+
+  it('an empty grant shows the full set', async () => {
+    const env = makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: '' } })
+    const r = await processFiles('sess-a', env, () => {}, 0, '')
+    expect((r.payload.entries as Entry[]).map((e) => e.name)).toEqual(['output', 'quotes'])
+  })
+
+  it('a grant naming an absent folder shows nothing', async () => {
+    const env = makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: 'jobs' } })
+    const r = await processFiles('sess-a', env, () => {}, 0, '')
+    expect(r.payload.entries).toEqual([])
+  })
+
+  it('the grant holds when browsing into a granted folder', async () => {
+    const env = makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: 'quotes' } })
+    const r = await processFiles('sess-a', env, () => {}, 0, 'quotes')
+    expect((r.payload.entries as Entry[]).map((e) => e.name)).toEqual(['CR2969', 'CR2974'])
+  })
+
+  it('logs granted=1 for a one-folder grant and granted=full for an empty grant', async () => {
+    const lines: string[] = []
+    await processFiles(
+      'sess-a',
+      makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: 'quotes' } }),
+      (l) => lines.push(l),
+      0,
+      '',
+    )
+    expect(lines.some((l) => l.includes('granted=1'))).toBe(true)
+    const full: string[] = []
+    await processFiles(
+      'sess-a',
+      makeEnv({ 'sess-a': { ownerId: 'alice', accountId: 'acc-a', folders: '' } }),
+      (l) => full.push(l),
+      0,
+      '',
+    )
+    expect(full.some((l) => l.includes('granted=full'))).toBe(true)
+  })
 })