@rubytech/create-maxy-code 0.1.501 → 0.1.502

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.501",
+  "version": "0.1.502",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/docs/superpowers/plans/2026-07-25-task-1974-uploads-intake-inbox.md

@@ -0,0 +1,235 @@
+# Task 1974 — uploads/ intake inbox Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Reclassify the account `uploads/` directory from tool-owned scratch to a temporary intake inbox, and add a `stranded-intake` reconcile count so a node file-reference left pointing into `uploads/` is visible.
+
+**Architecture:** Doctrine plus audit change, no code path change. Three prose files are edited (`SCHEMA.md`, `data-manager.md`, `internals.md`), then the `platform-architecture` SKILL.md twin is regenerated from the docs corpus so the no-drift gate passes. Detection-only, mirroring the outbound `output/` rule landed by task 1930.
+
+**Tech Stack:** Markdown doctrine files; Node regen scripts (`docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`); the drift gate `maxy-code/platform/scripts/check-architecture-skill-no-drift.mjs`; the bash test `fs-schema-guard.test.sh`.
+
+## Global Constraints
+
+- Zero em-dashes in all shipped prose.
+- The 1930 outbound rule must survive intact: the `output/` promote-out sentence and the `scratch-refs` / `stranded` counts stay present. `stranded-intake` is appended to the output contract, never a rename of `stranded`.
+- `uploads` stays in the `allowed-top-level` block of SCHEMA.md (files still land there).
+- The write-path guard, the admin-UI upload handler, and `memory-ingest` `sourcePath` behaviour are unchanged.
+- Reconcile output contract after this task: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+- Paths are relative to the `maxy-code/` subtree root inside the worktree.
+
+---
+
+### Task 1: SCHEMA.md — reclassify uploads/ as intake inbox
+
+**Files:**
+- Modify: `platform/templates/account-schema/SCHEMA.md:31-39`
+
+**Interfaces:**
+- Produces: the doctrine text data-manager.md and internals.md refer to. No code symbols.
+
+- [ ] **Step 1: Remove `uploads/` from the "recreated on the next write" list.**
+
+At `SCHEMA.md:36-39`, change the list so `uploads/` is no longer among tool-owned rebuilt dirs:
+
+```
+The internal structure of these is owned by the writing tool and is recreated on
+the next write: `url-get/`, `output/`, `generated/`, `extracted/`,
+any published/served tree (`sites/`, `public/`), `agents/`, `specialists/`, and
+platform-internal areas (`cache/`, `secrets/`, `state/`, `logs/`, `tmp/`).
+```
+
+- [ ] **Step 2: Add the intake-inbox rule paragraph.**
+
+Immediately after the `output/` promote-out paragraph (ends at `SCHEMA.md:34`), insert a new paragraph. It states uploads is a temporary intake inbox, a file is promoted to its canonical bucket when its node is created, no persisted graph reference points into `uploads/`, and the per-`<attachmentId>` reason it is safe to move out of (unlike `output/`):
+
+```
+`uploads/` is a temporary intake inbox, not rebuilt scratch. A file lands at
+`uploads/<attachmentId>/` on upload and is promoted to its canonical entity
+bucket when its graph node is created: a Person or Organization file to
+`contacts/<name>/`, a Project file to `projects/<name>/`, anything else to
+`documents/`. A persisted graph reference must never point into `uploads/`.
+Unlike `output/`, each upload writes its own `uploads/<attachmentId>/` dir and no
+tool walks or rebuilds the subtree, so promoting a file out of it through the
+`data-manager` specialist is safe.
+```
+
+- [ ] **Step 3: Verify the edit.**
+
+Run:
+```bash
+cd platform/templates/account-schema
+# uploads no longer in the recreated-on-next-write list
+awk '/recreated on/,/logs.*tmp/' SCHEMA.md | grep -c 'uploads/' | grep -qx 0 && echo "OK: uploads removed from scratch list"
+# intake-inbox rule present
+grep -q 'temporary intake inbox' SCHEMA.md && echo "OK: intake rule present"
+# uploads still allowed-top-level
+grep -A40 'allowed-top-level' SCHEMA.md | grep -qx 'uploads' && echo "OK: uploads still allowed-top-level"
+# 1930 output/ rule survives
+grep -q 'promoted out of `output/`' SCHEMA.md && echo "OK: 1930 output rule intact"
+# zero em-dashes in this file
+! grep -q '—' SCHEMA.md && echo "OK: no em-dash"
+```
+Expected: all five OK lines.
+
+- [ ] **Step 4: Commit.**
+
+```bash
+git add platform/templates/account-schema/SCHEMA.md
+git commit -m "task: reclassify uploads/ as intake inbox in account SCHEMA.md (1974)"
+```
+
+---
+
+### Task 2: data-manager.md — reconcile case (e), walk uploads/, promotion permission, output contract
+
+**Files:**
+- Modify: `platform/templates/specialists/agents/data-manager.md:24` (reconcile brief), `:30` (output contract), and the "What success looks like" area for the promotion permission.
+
+**Interfaces:**
+- Consumes: the SCHEMA.md intake-inbox rule from Task 1.
+- Produces: the `stranded-intake=R` field that internals.md documents in Task 3.
+
+- [ ] **Step 1: Add reconcile case (e) and include uploads/ in the walk.**
+
+At `data-manager.md:24`, extend the counted list. After case (d), add case (e): a graph file-reference that resolves into `uploads/`, the inbound intake mirror of the `output/` scratch case. State that the walk now includes `uploads/` (a file under `uploads/` with no referencing node folds into `unreachable`). Exact appended clause inside the sentence that enumerates (a) to (d):
+
+```
+, and (e) graph file-references that resolve into the `uploads/` intake inbox,
+which is a temporary landing area a file should have been promoted out of when
+its node was created. The walk now includes `uploads/`; a file under `uploads/`
+that no node references counts under (a) unreachable.
+```
+
+- [ ] **Step 2: Add the stewardship promotion permission for uploads/.**
+
+In "## What success looks like" (after `data-manager.md:16`, the paired-move paragraph), add a sentence permitting promotion out of `uploads/`:
+
+```
+- A file in the `uploads/` intake inbox whose graph node exists is promoted to
+  its canonical bucket (Person or Organization to `contacts/<name>/`, Project to
+  `projects/<name>/`, else `documents/`), paired with a `database-operator`
+  `sourcePath` update in the same pass, exactly as any other move.
+```
+
+- [ ] **Step 3: Change the output contract.**
+
+At `data-manager.md:30`, change the reconcile summary line:
+
+```
+For the reconcile audit: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+- [ ] **Step 4: Verify the edit.**
+
+Run:
+```bash
+cd platform/templates/specialists/agents
+grep -q 'stranded-intake=R' data-manager.md && echo "OK: contract has stranded-intake"
+grep -q 'scratch-refs=P stranded=Q' data-manager.md && echo "OK: 1930 fields survive"
+grep -q '(e) graph file-references that resolve into the `uploads/`' data-manager.md && echo "OK: case e present"
+grep -q 'promoted to' data-manager.md && grep -q 'sourcePath` update' data-manager.md && echo "OK: promotion permission present"
+! grep -q '—' data-manager.md && echo "OK: no em-dash"
+```
+Expected: five OK lines.
+
+- [ ] **Step 5: Commit.**
+
+```bash
+git add platform/templates/specialists/agents/data-manager.md
+git commit -m "task: data-manager reconcile counts uploads/ intake drift as stranded-intake (1974)"
+```
+
+---
+
+### Task 3: internals.md — document the reclassification and the stranded-intake count
+
+**Files:**
+- Modify: `platform/plugins/docs/references/internals.md:411`
+
+**Interfaces:**
+- Consumes: the reconcile contract from Task 2.
+- Produces: the corpus text the architecture SKILL.md twin regenerates from in Task 4.
+
+- [ ] **Step 1: Append the intake-inbox rule to the placement paragraph.**
+
+At `internals.md:411`, the sentence currently ends: "...is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up." Extend it with the inbound mirror. Append after the `scratch-refs`/`stranded` clause:
+
+```
+The inbound mirror is the `uploads/` intake inbox: an uploaded file lands at `uploads/<attachmentId>/` and is promoted to its canonical entity bucket when its graph node is created, so a persisted node reference resolving into `uploads/` is intake drift, counted by the same reconcile audit as `stranded-intake`. Unlike `output/`, `uploads/` is never rebuilt by a tool, so the `data-manager` may promote a file out of it. The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+- [ ] **Step 2: Verify the edit.**
+
+Run:
+```bash
+grep -q 'stranded-intake' platform/plugins/docs/references/internals.md && echo "OK: internals mentions count"
+grep -q 'intake inbox' platform/plugins/docs/references/internals.md && echo "OK: internals mentions reclassification"
+! grep -q '—' platform/plugins/docs/references/internals.md && echo "OK: no em-dash added"
+```
+Expected: three OK lines. (The last check should already pass before the edit; keep the added prose em-dash-free.)
+
+- [ ] **Step 3: Commit.**
+
+```bash
+git add platform/plugins/docs/references/internals.md
+git commit -m "task: internals.md documents uploads/ intake inbox and stranded-intake count (1974)"
+```
+
+---
+
+### Task 4: Regenerate the architecture skill twin and pass the gates
+
+**Files:**
+- Modify (generated): `platform/plugins/admin/skills/platform-architecture/SKILL.md`
+- Run: `docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`, `platform/scripts/check-architecture-skill-no-drift.mjs`, `platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh`
+
+**Interfaces:**
+- Consumes: the edited internals.md from Task 3.
+- Produces: a SKILL.md byte-equal to what the gate regenerates.
+
+- [ ] **Step 1: Regenerate the corpus and the skill twin.**
+
+Run from the worktree repo root:
+```bash
+node docs/scripts/copy-docs.mjs
+node maxy-code/scripts/assemble-architecture-skill.mjs --brand maxy-code
+```
+Expected: `[copy-docs]` and `[platform-arch-assemble] op=write` lines, no error.
+
+- [ ] **Step 2: Run the drift gate.**
+
+Run:
+```bash
+node maxy-code/platform/scripts/check-architecture-skill-no-drift.mjs --brand maxy-code
+```
+Expected: exit 0, no drift reported. If it reports drift, the regen in Step 1 did not run or the SKILL.md was not re-written; re-run Step 1.
+
+- [ ] **Step 3: Run the write-guard test (regression boundary).**
+
+Run:
+```bash
+bash maxy-code/platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh
+```
+Expected: all assertions pass. The guard is unchanged; `uploads/` is still an allowed write, so this stays green.
+
+- [ ] **Step 4: Commit the regenerated twin (and any corpus artefact the gate expects committed).**
+
+```bash
+git add platform/plugins/admin/skills/platform-architecture/SKILL.md
+git status --porcelain docs/public
+# stage docs/public/llms-full.*.txt only if it is a tracked artefact that changed
+git commit -m "task: regenerate platform-architecture skill twin for 1974"
+```
+
+---
+
+## Land (Phase 6 handles this — not an implementation task)
+
+LANES.md and task-file archival are done in Phase 6c of the sprint, not here. The task's "LANES Ready row" line describes the pre-implementation state; because this sprint implements and archives in one motion, the end state is: task file under `.tasks/archive/`, no Ready row referencing 1974, and the archive sentence naming 1974. This is a deliberate deviation from the task's literal LANES line, recorded in Plan Conformity.
+
+## Self-Review
+
+- **Spec coverage:** SCHEMA.md reclassification (Task 1), data-manager.md case (e) + walk + promotion + contract (Task 2), internals.md + twin regen (Tasks 3-4), LANES (Phase 6c). Every in-scope item maps to a task.
+- **Out of scope confirmed untouched:** no auto-promotion hook, no cadence (1931), no CC-native uploads reach, no write-guard edit, no ingest-path edit.
+- **Type consistency:** the single shared token is the output-contract string; it reads `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R` identically in Tasks 2 and 3.
+- **Placeholder scan:** none; every edit carries its literal text.

package/payload/platform/docs/superpowers/plans/2026-07-25-task-1976-intra-folder-hygiene.md

@@ -0,0 +1,215 @@
+# Task 1976 Intra-folder Filing Hygiene Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Teach the `data-manager` reconcile audit to count three intra-folder drift kinds (superseded versions, format twins, stray subfolders) and state the three governing rules in `SCHEMA.md`, `data-manager.md`, and `internals.md`, so version and format sprawl becomes visible before a cleanup is asked for.
+
+**Architecture:** Detection-and-doctrine only, matching the 1930/1974 precedent. Three markdown source files gain the rules and counts; the `platform-architecture/SKILL.md` twin is regenerated from `internals.md` by the assembler, never hand-edited. No new write-time guard, no automatic deletion.
+
+**Tech Stack:** Markdown templates, Node ESM regen scripts (`docs/scripts/copy-docs.mjs`, `maxy-code/scripts/assemble-architecture-skill.mjs`), Bash test harness (`fs-schema-guard.test.sh`), drift gate (`check-architecture-skill-no-drift.mjs`).
+
+## Global Constraints
+
+- Zero em-dashes in shipped prose (use commas, colons, or full stops).
+- Detection-only: the reconcile audit counts, it never removes. Removal is a stewardship dispatch under operator direction (deletion is destructive).
+- The three new fields are **appended** to the output contract, never substituted: `scratch-refs`, `stranded`, and `stranded-intake` all survive.
+- The no-subfolder rule is scoped to `projects/<name>/` and `contacts/<name>/` only. `documents/` is allowed one document-folder deep (`documents/<doc>/file`) and is out of scope for the subfolder rule.
+- Version-group definition: `<base>.ext` and `<base>-vN.ext` sharing basename stem and extension are versions of one deliverable.
+- Format-twin definition: same basename where a delivered `.pdf` sits beside its source render `.html`/`.md`; count the source renders whose delivered twin exists.
+- The reconcile has no automated harness (it runs as a Sonnet agent). Verification of the counts is manual on a seeded folder; the automated gates that must stay green are `fs-schema-guard.test.sh` and `check-architecture-skill-no-drift.mjs`.
+
+---
+
+### Task 1: SCHEMA.md — Intra-folder hygiene section
+
+**Files:**
+- Modify: `platform/templates/account-schema/SCHEMA.md` (insert a new `## Intra-folder hygiene` section between `## Naming convention` and `## Tool-owned`)
+
+**Interfaces:**
+- Produces: the three named rules (current-version-only, one-canonical-format, no-subfolder) that Task 2 and Task 3 reference by name.
+
+- [ ] **Step 1: Insert the section** after the Naming convention section (currently ending at line 27), before `## Tool-owned`:
+
+```markdown
+## Intra-folder hygiene
+
+The operator-data buckets hold one current copy of each deliverable, in one
+canonical format, with no subtree. Three rules keep them that way; the standing
+reconcile counts any that predate them, and `data-manager` clears them on a
+stewardship dispatch.
+
+- **Current version only.** `<base>.ext` and `<base>-vN.ext` (for example
+  `charlotte-deck.pdf` and `charlotte-deck-v2.pdf` through
+  `charlotte-deck-v6.pdf`) are versions of one deliverable, not separate files.
+  Keep the newest; the superseded copies are removed through `data-manager`.
+- **One canonical format.** A delivered `.pdf` and its source render sharing the
+  same basename (`charlotte-deck.html` beside `charlotte-deck.pdf`,
+  `invoice-rbt-2026-005.html` beside `invoice-rbt-2026-005.pdf`) are one
+  deliverable in two formats. The pdf is the deliverable; the `.html` or `.md`
+  render that produced it is not a second one and is removed through
+  `data-manager`.
+- **No subfolder.** No folder nests under `projects/<name>/` or
+  `contacts/<name>/`; files live directly inside the entity folder. This is the
+  flat rule from the buckets above, restated as a standing invariant: the write
+  guard blocks the depth as you create it, and the reconcile counts any subtree
+  that predates the guard or was created off-path.
+```
+
+- [ ] **Step 2: Verify the section reads and has no em-dashes**
+
+Run: `grep -n 'Intra-folder hygiene' platform/templates/account-schema/SCHEMA.md && ! grep -n '—' platform/templates/account-schema/SCHEMA.md && echo "no em-dash"`
+Expected: the heading line prints, then `no em-dash`.
+
+- [ ] **Step 3: Verify the write guard is untouched (green baseline holds)**
+
+Run: `bash platform/plugins/admin/hooks/__tests__/fs-schema-guard.test.sh 2>&1 | tail -1`
+Expected: `----- 22 passed, 0 failed -----`
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add platform/templates/account-schema/SCHEMA.md
+git commit -m "task: SCHEMA.md states intra-folder hygiene rules (1976)"
+```
+
+---
+
+### Task 2: data-manager.md — three counts, output contract, stewardship
+
+**Files:**
+- Modify: `platform/templates/specialists/agents/data-manager.md` (reconcile brief at line 25, output contract at line 31, "What success looks like" at line 17)
+
+**Interfaces:**
+- Consumes: the three rule names from Task 1.
+- Produces: the output-contract line `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U` that Task 3 mirrors verbatim.
+
+- [ ] **Step 1: Extend the reconcile brief** (line 25). Insert immediately before `Move nothing, dispatch nothing.`:
+
+```
+Then, per operator-data entity folder (`projects/<name>/`, `contacts/<name>/`), count three intra-folder drifts from disk structure alone, no graph resolution needed: (f) files in a version group, where `<base>.ext` and `<base>-vN.ext` share a basename stem and extension and all but the newest are superseded, counting every superseded copy as `versioned`; (g) format twins, a source-render file (`.html`, `.md`) whose delivered `.pdf` twin of the same basename sits in the same folder, counting each such render as `format-twins`; (h) stray subfolders nested under an entity folder, which the flat rule forbids, counting each subfolder as `stray-subdir`.
+```
+
+- [ ] **Step 2: Extend the output contract** (line 31). Change the reconcile-audit string from:
+
+```
+`unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`
+```
+
+to:
+
+```
+`unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`
+```
+
+- [ ] **Step 3: Add the stewardship bullet** to "What success looks like", immediately after the `uploads/` promotion bullet (line 17):
+
+```
+- Superseded versions and redundant format twins are removed, and a subfolder nested under `projects/<name>/` or `contacts/<name>/` is flattened or re-filed, when a stewardship brief asks for it. Each removal or move pairs with a `database-operator` reference update in the same pass, exactly as any other move: the surviving current render keeps the node reference, and a removed file's node is repointed or its reference dropped. Removal is destructive, so it happens only on an explicit stewardship dispatch, never in the read-only reconcile audit.
+```
+
+- [ ] **Step 4: Verify the contract line and no em-dashes**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/templates/specialists/agents/data-manager.md && grep -o 'scratch-refs=P stranded=Q stranded-intake=R' platform/templates/specialists/agents/data-manager.md && ! grep '—' platform/templates/specialists/agents/data-manager.md && echo "no em-dash"`
+Expected: `1`, then the preserved `scratch-refs=P stranded=Q stranded-intake=R` fragment, then `no em-dash`.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add platform/templates/specialists/agents/data-manager.md
+git commit -m "task: data-manager reconcile counts versioned/format-twins/stray-subdir (1976)"
+```
+
+---
+
+### Task 3: internals.md — reconcile rules and contract string
+
+**Files:**
+- Modify: `platform/plugins/docs/references/internals.md` (the reconcile paragraph at line 411)
+
+**Interfaces:**
+- Consumes: the output-contract line from Task 2 (must match verbatim).
+- Produces: the corpus source the assembler reads to regenerate the SKILL.md twin in Task 4.
+
+- [ ] **Step 1: Insert the intra-folder description** into line 411, immediately before the final sentence `The reconcile output contract is ...`:
+
+```
+Beyond placement and intake, the same audit counts intra-folder sprawl inside each operator-data entity folder from disk structure alone: superseded version copies (`<base>.ext` and `<base>-vN.ext` are one deliverable, all but the newest counted `versioned`), format twins (a source `.html`/`.md` render kept beside its delivered `.pdf` of the same basename, counted `format-twins`), and subfolders nested under `projects/<name>/` or `contacts/<name>/` that the flat rule forbids (counted `stray-subdir`). These are read-only counts; removal or flattening happens only on a `data-manager` stewardship dispatch, each paired with a `database-operator` reference update.
+```
+
+- [ ] **Step 2: Update the contract string** in the same paragraph, from:
+
+```
+The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R`.
+```
+
+to:
+
+```
+The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`.
+```
+
+- [ ] **Step 3: Verify the string matches Task 2 and no em-dashes in the changed region**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' platform/plugins/docs/references/internals.md && grep -o 'counted `stray-subdir`' platform/plugins/docs/references/internals.md`
+Expected: `1`, then `counted `stray-subdir``.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add platform/plugins/docs/references/internals.md
+git commit -m "task: internals.md documents intra-folder hygiene counts (1976)"
+```
+
+---
+
+### Task 4: Regenerate the platform-architecture SKILL.md twin and gate it
+
+**Files:**
+- Regenerate (do not hand-edit): `platform/plugins/admin/skills/platform-architecture/SKILL.md`
+
+**Interfaces:**
+- Consumes: the edited `internals.md` from Task 3 (via the docs corpus).
+
+- [ ] **Step 1: Rebuild the docs corpus** (mirrors internals.md into `docs/public/llms-full.<brand>.txt`). From the repo root:
+
+Run: `cd "$(git rev-parse --show-toplevel)" && node docs/scripts/copy-docs.mjs 2>&1 | tail -2`
+Expected: no error.
+
+- [ ] **Step 2: Assemble both brand skills** (the maxy-code run writes SKILL.md):
+
+Run: `cd "$(git rev-parse --show-toplevel)" && node maxy-code/scripts/assemble-architecture-skill.mjs --brand maxy-code && node maxy-code/scripts/assemble-architecture-skill.mjs --brand realagent-code`
+Expected: `[platform-arch-assemble] op=write brand=maxy-code path=.../SKILL.md ...`.
+
+- [ ] **Step 3: Run the drift gate**
+
+Run: `cd maxy-code && node platform/scripts/check-architecture-skill-no-drift.mjs 2>&1 | tail -3`
+Expected: `[check-architecture-skill-no-drift] ok brand=maxy-code (...)` and `... ok brand=realagent-code (...)`.
+
+- [ ] **Step 4: Confirm the new fields reached the regenerated twin**
+
+Run: `grep -c 'versioned=S format-twins=T stray-subdir=U' maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md`
+Expected: `1` (or more).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add maxy-code/platform/plugins/admin/skills/platform-architecture/SKILL.md maxy-code/docs docs/public 2>/dev/null; git add -A
+git commit -m "task: regenerate platform-architecture skill twin for 1976"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- SCHEMA.md three rules → Task 1. ✓
+- data-manager three counts + contract + stewardship → Task 2. ✓
+- internals.md rules + counts → Task 3. ✓
+- SKILL.md regenerated twin → Task 4. ✓
+- LANES.md Ready row + archive → Phase 6 of the sprint (not a plan task; the sprint owns archive/LANES). ✓
+
+**Placeholder scan:** every edit shows verbatim insert text. No TBD/TODO. ✓
+
+**Type consistency:** the output-contract string is byte-identical in Task 2, Task 3, and the Task 4 grep: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`. ✓
+
+**Out of scope (deferred, no task needed here):** automatic deletion, a write-time guard for versions/twins, per-vertical canonical-format policy, the `uploads/` intake (1974, landed), the `/data` 524 (1975, archived), the `output/` promote-out counts (1930, landed). These are stated out-of-scope in the task brief, not dropped work.

package/payload/platform/plugins/admin/skills/platform-architecture/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: platform-architecture
 description: Use when grounding any documented-surface claim about what Maxy ships — plugins, skills, specialists, install/deploy flows, internals. This is the install catalogue, not evidence of what is enabled on the current account. For install state on this account, call `capabilities-here`; for documented surface, cite the `Source:` URL inline.
-content-hash: sha256:70e0125f4ead8ba83c01b87f6a9ccc15f51d9492c5dd55bd4f83106769280a7e
+content-hash: sha256:f78dfe81d9832fd7197627e1cf770c730bb2d16b4b640f1a47558e86acfe0db8
 brand: maxy-code
 product-name: Maxy
 ---
@@ -4354,7 +4354,7 @@ Standing rules the operator gives over a channel are `Preference` nodes. Two mec
 
 **Observability.** `[preference-write] op=reconcile … mode=<reinforce|update|contradict|new> similarity=…` — a stream of `mode=new` for subjects that already exist is the duplicate-minting signature. `[preference-inject] op=inject channel=<wa|tg|web> injected=<N> owner=<8> source=<owner|no-owner|owner-error|fetch-error>` — injection selects only the account owner's admin preferences, so `source=owner injected=0` is a genuinely empty owner, `source=no-owner` is an account with no seeded owner (injects nothing, a missed owner seeding), and `injected=0 source=owner` on an account whose owner holds rules is the write-only regression re-appearing. `[preference-inject] op=reconcile accountId=… stored=… injected=…` — the standing reconciliation audit (claude-session-manager, 5-minute tick) flags any account whose stored active count diverges from what injection surfaces; injection now surfaces every stored active preference verbatim, so `stored == injected` is the healthy signal and any gap is a dropped-row regression (a reintroduced cap, filter, or truncation). A clean pass logs `op=reconcile drifted=0`, the no-event detector.
 
-**Consult-before-send gate.** Injection (above) puts the owner's active rules in front of every channel turn, but the growing layer-2 `Preference` set is read on demand with `profile-read`, a per-turn judgement the agent can skip, the miss that dropped a customer signature on a delivered document. `hooks/preference-consult-gate.sh` (admin plugin) is the deliverable-boundary enforcement: a PreToolUse gate on customer-facing document deliverables (`browser-pdf-save`/`SendUserFile` to `memory/users/<phone>/documents/`, and email/Outlook sends carrying attachments) that blocks (exit 2) when no `profile-read` ran after the last user message in the transcript. It fires on documents only, never on casual replies. **Observability:** `[preference-gate] op=allow tool=<name> consulted=true` on an allowed document deliverable, `op=bypass tool=<name> detail=no profile-read this turn` on a block; a stream of `op=bypass` is the un-consulted-send signature. The advisory companion `hooks/preference-consult-directive.sh` injects the two-layer architecture reminder every turn (`[pref-wrapper] op=inject`). The placement half, promoting finished deliverables out of `output/` scratch, is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up.
+**Consult-before-send gate.** Injection (above) puts the owner's active rules in front of every channel turn, but the growing layer-2 `Preference` set is read on demand with `profile-read`, a per-turn judgement the agent can skip, the miss that dropped a customer signature on a delivered document. `hooks/preference-consult-gate.sh` (admin plugin) is the deliverable-boundary enforcement: a PreToolUse gate on customer-facing document deliverables (`browser-pdf-save`/`SendUserFile` to `memory/users/<phone>/documents/`, and email/Outlook sends carrying attachments) that blocks (exit 2) when no `profile-read` ran after the last user message in the transcript. It fires on documents only, never on casual replies. **Observability:** `[preference-gate] op=allow tool=<name> consulted=true` on an allowed document deliverable, `op=bypass tool=<name> detail=no profile-read this turn` on a block; a stream of `op=bypass` is the un-consulted-send signature. The advisory companion `hooks/preference-consult-directive.sh` injects the two-layer architecture reminder every turn (`[pref-wrapper] op=inject`). The placement half, promoting finished deliverables out of `output/` scratch, is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up. The inbound mirror is the `uploads/` intake inbox: an uploaded file lands at `uploads/<attachmentId>/` and is promoted to its canonical entity bucket when its graph node is created, so a persisted node reference resolving into `uploads/` is intake drift, counted by the same reconcile audit as `stranded-intake`. Unlike `output/`, `uploads/` is never rebuilt by a tool, so the `data-manager` may promote a file out of it. Beyond placement and intake, the same audit counts intra-folder sprawl inside each operator-data entity folder from disk structure alone: superseded version copies (`<base>.ext` and `<base>-vN.ext` are one deliverable, all but the newest counted `versioned`), format twins (a source `.html`/`.md` render kept beside its delivered `.pdf` of the same basename, counted `format-twins`), and subfolders nested under `projects/<name>/` or `contacts/<name>/` that the flat rule forbids (counted `stray-subdir`). These are read-only counts; removal or flattening happens only on a `data-manager` stewardship dispatch, each paired with a `database-operator` reference update. The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`.
 
 ---
 

package/payload/platform/plugins/admin/skills/whats-new/SKILL.md

@@ -9,6 +9,13 @@ Invoked by the admin agent directly.
 
 This is the platform's release timeline, newest first. Each entry shows the date it shipped and the version it shipped in, so you can tell the operator how current their install is. To compare, read the installed version from `capabilities-here` and match it against the versions below. Keep answers high level and in plain English; this is a summary, not a full commit log.
 
+## 2026-07-25 (0.1.502)
+
+- Uploading a file from the phone or desktop app now shows as a proper thumbnail in chat, not a raw file path.
+- Switching accounts now shows a loading screen and lands you on the dashboard instead of a blank page.
+- Uploaded files are automatically filed into the right folder instead of sitting in a temporary holding area.
+- Searching your files is more reliable and no longer times out on larger accounts.
+
 ## 2026-07-21 (0.1.482)
 
 - WhatsApp now runs a separate connection for each client account, so one client's messages never mix with another's.

package/payload/platform/plugins/docs/references/internals.md

@@ -408,7 +408,7 @@ Standing rules the operator gives over a channel are `Preference` nodes. Two mec
 
 **Observability.** `[preference-write] op=reconcile … mode=<reinforce|update|contradict|new> similarity=…` — a stream of `mode=new` for subjects that already exist is the duplicate-minting signature. `[preference-inject] op=inject channel=<wa|tg|web> injected=<N> owner=<8> source=<owner|no-owner|owner-error|fetch-error>` — injection selects only the account owner's admin preferences, so `source=owner injected=0` is a genuinely empty owner, `source=no-owner` is an account with no seeded owner (injects nothing, a missed owner seeding), and `injected=0 source=owner` on an account whose owner holds rules is the write-only regression re-appearing. `[preference-inject] op=reconcile accountId=… stored=… injected=…` — the standing reconciliation audit (claude-session-manager, 5-minute tick) flags any account whose stored active count diverges from what injection surfaces; injection now surfaces every stored active preference verbatim, so `stored == injected` is the healthy signal and any gap is a dropped-row regression (a reintroduced cap, filter, or truncation). A clean pass logs `op=reconcile drifted=0`, the no-event detector.
 
-**Consult-before-send gate.** Injection (above) puts the owner's active rules in front of every channel turn, but the growing layer-2 `Preference` set is read on demand with `profile-read`, a per-turn judgement the agent can skip, the miss that dropped a customer signature on a delivered document. `hooks/preference-consult-gate.sh` (admin plugin) is the deliverable-boundary enforcement: a PreToolUse gate on customer-facing document deliverables (`browser-pdf-save`/`SendUserFile` to `memory/users/<phone>/documents/`, and email/Outlook sends carrying attachments) that blocks (exit 2) when no `profile-read` ran after the last user message in the transcript. It fires on documents only, never on casual replies. **Observability:** `[preference-gate] op=allow tool=<name> consulted=true` on an allowed document deliverable, `op=bypass tool=<name> detail=no profile-read this turn` on a block; a stream of `op=bypass` is the un-consulted-send signature. The advisory companion `hooks/preference-consult-directive.sh` injects the two-layer architecture reminder every turn (`[pref-wrapper] op=inject`). The placement half, promoting finished deliverables out of `output/` scratch, is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up.
+**Consult-before-send gate.** Injection (above) puts the owner's active rules in front of every channel turn, but the growing layer-2 `Preference` set is read on demand with `profile-read`, a per-turn judgement the agent can skip, the miss that dropped a customer signature on a delivered document. `hooks/preference-consult-gate.sh` (admin plugin) is the deliverable-boundary enforcement: a PreToolUse gate on customer-facing document deliverables (`browser-pdf-save`/`SendUserFile` to `memory/users/<phone>/documents/`, and email/Outlook sends carrying attachments) that blocks (exit 2) when no `profile-read` ran after the last user message in the transcript. It fires on documents only, never on casual replies. **Observability:** `[preference-gate] op=allow tool=<name> consulted=true` on an allowed document deliverable, `op=bypass tool=<name> detail=no profile-read this turn` on a block; a stream of `op=bypass` is the un-consulted-send signature. The advisory companion `hooks/preference-consult-directive.sh` injects the two-layer architecture reminder every turn (`[pref-wrapper] op=inject`). The placement half, promoting finished deliverables out of `output/` scratch, is counted by the `data-manager` reconcile audit (`scratch-refs`, `stranded`); making that audit run on a standing periodic cadence is a filed follow-up. The inbound mirror is the `uploads/` intake inbox: an uploaded file lands at `uploads/<attachmentId>/` and is promoted to its canonical entity bucket when its graph node is created, so a persisted node reference resolving into `uploads/` is intake drift, counted by the same reconcile audit as `stranded-intake`. Unlike `output/`, `uploads/` is never rebuilt by a tool, so the `data-manager` may promote a file out of it. Beyond placement and intake, the same audit counts intra-folder sprawl inside each operator-data entity folder from disk structure alone: superseded version copies (`<base>.ext` and `<base>-vN.ext` are one deliverable, all but the newest counted `versioned`), format twins (a source `.html`/`.md` render kept beside its delivered `.pdf` of the same basename, counted `format-twins`), and subfolders nested under `projects/<name>/` or `contacts/<name>/` that the flat rule forbids (counted `stray-subdir`). These are read-only counts; removal or flattening happens only on a `data-manager` stewardship dispatch, each paired with a `database-operator` reference update. The reconcile output contract is `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`.
 
 ---
 

package/payload/platform/templates/account-schema/SCHEMA.md

@@ -26,6 +26,32 @@ the client data portal, and case-sensitive matching. The write guard blocks a ba
 name as you create it, and the standing reconcile counts any that predate the
 rule. Renaming an existing bad name goes through the `data-manager` specialist.
 
+## Intra-folder hygiene
+
+The `projects/<name>/` and `contacts/<name>/` entity folders hold one current
+copy of each deliverable, in one canonical format, with no subtree. Three rules
+keep them that way; the standing reconcile counts any that predate them, and
+`data-manager` clears them on a stewardship dispatch. (`documents/` is exempt: it
+may hold one document-folder deep per the buckets above, so these rules do not
+apply there.)
+
+- **Current version only.** `<base>.ext` and `<base>-vN.ext` (for example
+  `charlotte-deck.pdf` and `charlotte-deck-v2.pdf` through
+  `charlotte-deck-v6.pdf`) are versions of one deliverable, not separate files.
+  Keep the highest-numbered version (the unsuffixed base is the original, so any
+  `-vN` supersedes it); the superseded copies are removed through `data-manager`.
+- **One canonical format.** A delivered `.pdf` and its source render sharing the
+  same basename (`charlotte-deck.html` beside `charlotte-deck.pdf`,
+  `invoice-rbt-2026-005.html` beside `invoice-rbt-2026-005.pdf`) are one
+  deliverable in two formats. The pdf is the deliverable; the `.html` or `.md`
+  render that produced it is not a second one and is removed through
+  `data-manager`.
+- **No subfolder.** No folder nests under `projects/<name>/` or
+  `contacts/<name>/`; files live directly inside the entity folder. This is the
+  flat rule from the buckets above, restated as a standing invariant: the write
+  guard blocks the depth as you create it, and the reconcile counts any subtree
+  that predates the guard or was created off-path.
+
 ## Tool-owned (off-limits — never reorganise)
 
 Finished deliverables must be promoted out of `output/` into `documents/` or
@@ -33,8 +59,17 @@ Finished deliverables must be promoted out of `output/` into `documents/` or
 last resort, and a graph reference must never point into it (the next tool write
 rebuilds the tree and the reference dangles).
 
+`uploads/` is a temporary intake inbox, not rebuilt scratch. A file lands at
+`uploads/<attachmentId>/` on upload and is promoted to its canonical entity
+bucket when its graph node is created: a Person or Organization file to
+`contacts/<name>/`, a Project file to `projects/<name>/`, anything else to
+`documents/`. A persisted graph reference must never point into `uploads/`.
+Unlike `output/`, each upload writes its own `uploads/<attachmentId>/` dir and no
+tool walks or rebuilds the subtree, so promoting a file out of it through the
+`data-manager` specialist is safe.
+
 The internal structure of these is owned by the writing tool and is recreated on
-the next write: `url-get/`, `output/`, `generated/`, `extracted/`, `uploads/`,
+the next write: `url-get/`, `output/`, `generated/`, `extracted/`,
 any published/served tree (`sites/`, `public/`), `agents/`, `specialists/`, and
 platform-internal areas (`cache/`, `secrets/`, `state/`, `logs/`, `tmp/`).
 `.quarantine/` is a historical store. An earlier version of the schema reconcile

package/payload/platform/templates/specialists/agents/data-manager.md

@@ -14,6 +14,8 @@ You are the steward of this account's data directory. Admin dispatches you throu
 - The account data directory is organised consistently with the graph ontology. Before the first move of a session, Read `platform/plugins/memory/references/schema-base.md`; when `brand.json#vertical` is set, also Read `platform/plugins/memory/references/schema-<vertical>.md`. Directory structure and file placement should make sense to someone navigating by the graph: files that belong to a Project, Person, or document node live where the node's references say they live.
 - Every operator file is reachable from a graph node, and every graph file-reference resolves to a real path. `memory-search` is how you resolve which nodes reference a file — search for the filename and the path before deciding anything about it.
 - A file is never moved without the referencing nodes being updated in the same pass. Moves and reference updates are paired operations: for each move, dispatch `database-operator` via the Task tool with a brief naming the node (elementId from your `memory-search`), the property holding the old path, and the new path. You have no graph-write tools by design — every graph mutation flows through database-operator.
+- A file in the `uploads/` intake inbox whose graph node exists is promoted to its canonical bucket (Person or Organization to `contacts/<name>/`, Project to `projects/<name>/`, else `documents/`), paired with a `database-operator` `sourcePath` update in the same pass, exactly as any other move. `uploads/` is a temporary landing area, not a tool-owned tree, so moving a file out of it is not a reorganisation of a system-convention directory.
+- Superseded versions and redundant format twins are removed, and a subfolder nested under `projects/<name>/` or `contacts/<name>/` is flattened or re-filed, when a stewardship brief asks for it. Each removal or move pairs with a `database-operator` reference update in the same pass, exactly as any other move: the surviving current render keeps the node reference, and a removed file's node is repointed or its reference dropped. Removal is destructive, so it happens only on an explicit stewardship dispatch, never in the read-only reconcile audit.
 
 ## Off-limits: system-convention directories
 
@@ -21,13 +23,13 @@ Directories whose layout is owned by tools are not yours to reorganise — a too
 
 ## The reconcile audit brief
 
-When admin's brief names a reconcile audit, the pass is read-only: walk the operator-file areas of the account directory, resolve each file against the graph via `memory-search`, and count (a) files unreachable from any graph node, (b) graph file-references that do not resolve to a real path, (c) graph file-references that resolve into a tool-owned scratch dir (`output/`, `generated/`, `extracted/`, `url-get/`), which the next tool write rebuilds so the reference is fragile by construction, and (d) deliverables a node references that resolve only under a scratch dir and were never promoted to `documents/` or `projects/`. Move nothing, dispatch nothing. The audit exists so a rising count is visible before anyone asks for a cleanup.
+When admin's brief names a reconcile audit, the pass is read-only: walk the operator-file areas of the account directory, resolve each file against the graph via `memory-search`, and count (a) files unreachable from any graph node, (b) graph file-references that do not resolve to a real path, (c) graph file-references that resolve into a tool-owned scratch dir (`output/`, `generated/`, `extracted/`, `url-get/`), which the next tool write rebuilds so the reference is fragile by construction, (d) deliverables a node references that resolve only under a scratch dir and were never promoted to `documents/` or `projects/`, and (e) graph file-references that resolve into the `uploads/` intake inbox, which is a temporary landing area a file should have been promoted out of when its node was created. The walk now includes `uploads/`; a file under `uploads/` that no node references counts under (a) unreachable. Then, per operator-data entity folder (`projects/<name>/`, `contacts/<name>/`), count three intra-folder drifts from disk structure alone, no graph resolution needed: (f) files in a version group, where `<base>.ext` and `<base>-vN.ext` share a basename stem and extension and all but the newest are superseded, counting every superseded copy as `versioned`; (g) format twins, a source-render file (`.html`, `.md`) whose delivered `.pdf` twin of the same basename sits in the same folder, counting each such render as `format-twins`; (h) stray subfolders nested under an entity folder, which the flat rule forbids, counting each subfolder as `stray-subdir`. Move nothing, dispatch nothing. The audit exists so a rising count is visible before anyone asks for a cleanup.
 
 When the vertical's `schema-<vertical>.md` declares a **published / served tree** with a Filesystem ↔ graph section (e.g. the per-listing site target with a URL ↔ path rule and an artefact → graph-reference table), the audit also walks that tree. The graph references it by hosted URL, not local path, so resolution runs through the section's URL ↔ path rule: for each served file, derive its hosted URL and check that some node references it; for each node URL **that matches the section's hosted-URL prefix**, derive its local path and check the file exists. Count served files matching no node reference in `unreachable` and prefix-matching node URLs resolving to no served file in `broken-refs`. Node URLs the rule cannot resolve — externally-hosted URLs (a CDN image, a third-party portal link) carry no served-tree prefix — are outside this audit and are never counted as broken. Honour the section's "served but intentionally unreferenced (tool / collateral)" list — those classes carry no reference by design and are never orphans, the same exclusion you already apply to the `url-get/` cache. This walk is still read-only: the served tree is a publish write target (off-limits to moves, above); the audit only counts drift, it never reorganises.
 
 ## Output contract
 
-End every dispatch with a one-line machine-greppable summary as the last line of your reply. For stewardship work: `moves=N ref-updates=M skipped=<reason|none>`. For the reconcile audit: `unreachable=N broken-refs=M scratch-refs=P stranded=Q`. If a brief is ambiguous about whether a directory is operator data or a system convention, name the ambiguity in your reply instead of guessing.
+End every dispatch with a one-line machine-greppable summary as the last line of your reply. For stewardship work: `moves=N ref-updates=M skipped=<reason|none>`. For the reconcile audit: `unreachable=N broken-refs=M scratch-refs=P stranded=Q stranded-intake=R versioned=S format-twins=T stray-subdir=U`. If a brief is ambiguous about whether a directory is operator data or a system convention, name the ambiguity in your reply instead of guessing.
 
 ## Review gates
 

package/payload/server/public/activity.html

@@ -5,12 +5,12 @@
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Activity — Maxy</title>
   <link rel="icon" href="/favicon.ico">
-  <script type="module" crossorigin src="/assets/activity-CVdVSw5V.js"></script>
+  <script type="module" crossorigin src="/assets/activity-DZFYDHNA.js"></script>
   <link rel="modulepreload" crossorigin href="/assets/chunk-CCr-iYLO.js">
-  <link rel="modulepreload" crossorigin href="/assets/useSubAccountSwitcher-CHwQhkaI.js">
-  <link rel="modulepreload" crossorigin href="/assets/AdminShell-BlbUNAPc.js">
-  <link rel="modulepreload" crossorigin href="/assets/triangle-alert-CngnWtjD.js">
-  <link rel="stylesheet" crossorigin href="/assets/useSubAccountSwitcher-yFQqnpQ8.css">
+  <link rel="modulepreload" crossorigin href="/assets/useSubAccountSwitcher-iQGqNJhI.js">
+  <link rel="modulepreload" crossorigin href="/assets/AdminShell-Gq8DU_ig.js">
+  <link rel="modulepreload" crossorigin href="/assets/triangle-alert-k8ulav-N.js">
+  <link rel="stylesheet" crossorigin href="/assets/useSubAccountSwitcher-fvBunpOC.css">
   <link rel="stylesheet" href="/brand-defaults.css">
 </head>
 <body>