@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/memory-dream/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: memory-dream
+scope: common
+role_scope: orchestrator-only
+description: |
+  Curate the workspace memory wiki as its appointed orchestrator. Trigger on a
+  Cloud-scheduled Dream task or a user's direct curation request. Inspect candidates
+  for orphan leaves, near-duplicates, stale pages, remote conflicts and oversized
+  hubs; browse the graph, cluster leaves into INDEX/hub/leaf structure, maintain
+  authored overview prose, split hubs, merge duplicates and verify/report changes.
+  Use memory_curate and memory_browse; preserve machine-generated hub TOCs and
+  graph-derived INDEX Contents. Orchestrator-only: write verbs reject other actors
+  with 403. Follow the body for safe mutation and verification procedures.
+applies_to: [hermes, claude-code, codex]
+version: 4
+---
+
+# Memory Dream — orchestrator-driven consolidation
+
+> **Memory pages are PKF (`.pkf`).** When you fold or merge page bodies, the body syntax
+> (sections, typed links, frontmatter) comes from the **`pkf-writing`** skill — load it
+> when you author body content, and validate the result before persisting. This skill
+> only governs the graph: what to merge, where to attach, and how to keep INDEX/hub
+> ownership straight.
+
+> **Candidate boundary.** Dream sees authoritative **Memory Pages**, not “all PKF.” A
+> message-inline PKF or Library `.pkf` Asset remains outside this loop. Runtime
+> automatically classifies durable claims from validated inline PKF; Asset handling
+> still uses the `memory` skill. Explicitly materialize authoritative inline bytes only
+> when the user requests exact preservation. Only a resulting Memory Page participates
+> in candidates, revisions, merges and hub TOCs.
+
+You are (when appointed) the **workspace memory orchestrator**. Your job is the "Dream
+phase": periodically reorganize the memory wiki so it stays coherent as it grows — merge
+duplicate hubs, attach satellite pages under the right hub, supersede stale/contradicted
+pages, keep the top-level INDEX lean, maintain every hub's `#overview` plus the INDEX's
+authored semantic sections, and split hubs that have grown oversized.
+
+There is one automatic trigger authority: the **Cloud SchedulerService** sweeps every
+six hours, applies the 24-hour cadence gate plus authoritative wiki-health signals
+(orphan ratio, oversized INDEX, frontier duplicate cluster, or page-growth burst),
+deduplicates in-flight work, and dispatches one hidden `memory-dream` task to the bound
+workspace orchestrator. The Cloud performs no Memory LLM reasoning. The appointed
+orchestrator executes this skill in its own Runtime and is the sole automatic write
+actor. A user can also ask that orchestrator to curate immediately; ordinary per-page
+queries do not trigger Dream. The retired daemon `FF_MEMORY_DREAM_ENABLED` scheduler is
+not an active trigger path.
+
+> **Authority gate.** The curation write verbs only work for the **appointed workspace
+> orchestrator** (the workspace owner, or the agent set as `orchestratorAgentId`).
+> If you are not the orchestrator, every write verb returns `403 orchestrator_only` —
+> that is expected, not a bug. Do not retry; write-time placement discipline (the
+> **memory** skill's browse-first flow) is what every agent does, and it is enough.
+
+**Owner vs orchestrator vs deputy (product209/16 MA-2):**
+
+- The **owner** (human) and the **appointed orchestrator**
+  (`orchestratorAgentId`) are the only Dream write actors. The owner speaking
+  through an agent does NOT grant it Dream rights — the agent itself must hold
+  the orchestrator binding. Dream never back-derives authority from "the owner
+  is talking to me".
+- A **deputy** does NOT inherit Dream from its bound member — not even when
+  the bound member is the owner. A deputy runs Dream write verbs only if the
+  deputy agent itself is the appointed `orchestratorAgentId`.
+- `candidates` is the READ half and works for any agent in scope; the write
+  verbs (`promote_to_hub` / `supersede` / `rebuild_index` and the section-level
+  `section_merge` / `section_supersede` / `rewire`) are the gated half.
+- `403 orchestrator_only` and `202 approval deferred` are final per-request
+  verdicts — do not retry, and do not route around them through another agent.
+
+## The verbs
+
+```
+memory_curate(op="candidates")                        # READ what needs work (any agent)
+memory_curate(op="candidates", kind="orphans")        # one surface; limit caps per kind
+memory_browse(query="<topic>")                        # READ the structure: {index, hubs[+snippet], nearest}
+memory_curate(op="promote_to_hub", pageId="<id>",
+              childPaths=["<path>", …])               # leaf → hub AND attach children (orchestrator only)
+memory_curate(op="supersede", pageId="<id>",
+              reason="merged into <path>")            # archive + mark stale (orchestrator only)
+memory_curate(op="rebuild_index")                     # regenerate hub TOCs; INDEX Contents stays graph-derived (orchestrator only)
+memory_curate(op="section_merge", pageId="<winnerPageId>",
+              targetSection="<winnerSlug>", sourcePageId="<loserPageId>",
+              sourceSection="<loserSlug>",
+              mergedContent="<merged body>")          # fold ONE near-duplicate section (memory211 W5)
+memory_curate(op="section_supersede", pageId="<pageId>",
+              section="<slug>")                       # retire ONE section in place (memory211 W5)
+memory_curate(op="rewire", linkId="<linkId>",
+              toPageId="<id>")                        # re-point a broken/wrong link (memory211 W5)
+```
+
+- `candidates` is the READ half: `{candidates:{orphans,duplicates,stale,conflicts,oversized}}`
+  — unplaced leaves (no outgoing `child-of`/`parent` edge to a live hub; an INDEX
+  `index-anchor` only guarantees reachability and therefore still counts as flat), near-duplicate clusters
+  (`duplicate_cluster:<peerIds>`), stale pages, remote-conflict pages, and oversized
+  hub/INDEX advisories (`kind="oversized"` — size is recorded, never machine-enforced;
+  splitting is YOUR call). It does NOT cluster or decide; that is YOUR LLM's job.
+- **`promote_to_hub` takes `childPaths[]`** — pass the member pages' paths (exactly as
+  candidates/browse returned them) and the cloud attaches them under the new hub as
+  `child-of` children **in the same call**. Do not promote a hollow hub and re-anchor
+  members one by one afterwards.
+- `rebuild_index` is the ONLY **hub** `#toc` writer. It emits a complete strict PKF
+  `<section>` with stable `data-sid`, one navigation entry per graph child and the
+  child's frontmatter `description`. Structural `child-of` remains child→hub in the
+  graph; downward TOC links are navigation, never inverted placement edges. Hub
+  `<h2 id="overview">` prose is agent territory and survives rebuild.
+- Top INDEX is different: its Contents is derived live from the graph and there is no
+  stored machine `#toc` to rebuild or edit. Its authored semantic sections are the
+  orchestrator's editorial territory.
+- **Section verbs (memory211 W5)** — the granularity drift happens at SECTION level, so
+  curation does too. `section_merge` rewrites the winner's section with `mergedContent`,
+  splices the loser section out of its page, and the CLOUD writes the
+  `supersedes` + `derived-from` provenance edges for you — a merge with no edge trail is
+  an unfinished merge. `section_supersede` retires one section (optionally pointing at the
+  surviving one). `rewire` fixes a single broken/wrong link without a page rewrite.
+- There is no `run_dream` cloud-LLM op — `candidates` (read) + the write ops are
+  the whole surface (memory203/13 §0.5: all memory LLM runs in your runtime, never the
+  cloud's).
+
+Enactment is the native `memory_curate` TOOL (the same tool surface every agent already
+holds, alongside `memory_search` / `memory_load` / `memory_browse` / `memory_write`). Do
+NOT look for a separate "memory-dream tool" or shell — `memory_curate` IS the enactment
+surface. (A `prismer memory curate …` CLI exists for shell contexts; the TOOL is primary.)
+If a curate response is `degraded:true`, no authoritative Cloud mutation occurred;
+report the degraded state and never describe the requested convergence as completed.
+
+## The convergence loop (keep it tight)
+
+Run the loop end-to-end in a handful of calls — `memory_browse` gives you the whole
+structure in ONE call, so you never need long exploratory search/load spelunking:
+
+**STEP 1 — READ the candidates.**
+
+```
+memory_curate(op="candidates")
+# → { ok:true, candidates: {
+#      orphans:    { items:[ {pageId, path, reason:"orphan"}, … ], total },
+#      duplicates: { items:[ {pageId, path, reason:"duplicate_cluster:<peerIds>"}, … ], total },
+#      stale:      { items:[ {pageId, path, reason}, … ], total },
+#      conflicts:  { items:[ {pageId, path, reason:"remote-conflict",
+#                             metadata:{…, latestTwoVersionSummaries}}, … ], total },
+#      oversized:  { items:[ {pageId, path, reason:"oversized:toc_entries,body_chars",
+#                             metadata:{bodyChars, tocEntries, softThresholds, advisory:true}}, … ], total } } }
+```
+
+**STEP 1b — REVIEW the conflicts.** `memory_curate(op="candidates", kind="conflicts")`
+lists pages whose current head landed via a remote-conflict LWW merge (two devices
+diverged); each item carries the latest two version summaries (changeSummary /
+authoredBy / createdAt) so you can judge which side won. For each one, confirm the
+head is correct — `memory_load` it and check the LWW winner didn't clobber the better
+content; if it did, `memory_write` the corrected body. Conflict is a STATE, not a
+brand: a curation touch or clean rewrite of the page clears it (an identical-content
+rewrite is a no-op and does NOT), so a reviewed page drops off this list on the next
+`candidates` read.
+
+**STEP 1c — REVIEW the oversized hubs.** `memory_curate(op="candidates",
+kind="oversized")` lists hubs whose body chars or stored TOC entry count exceeds the
+advisory soft thresholds, plus INDEX advisories based on its authored body size (its
+Contents is graph-derived). These are **split suggestions, never enforcement** — a
+lean hub (overview + TOC) keeps every multi-hop recall fast. For a hub with too many
+children, split by sub-topic: pick the natural anchor leaf of each sub-cluster,
+`promote_to_hub` it WITH its `childPaths`, and the moved children drop out of the
+parent's TOC on the next rebuild. A hub that is oversized because its overview prose
+grew into an essay: move the essay's durable content into a leaf under the hub and
+shrink the overview back to a summary. Use your judgment — an advisory you deliberately
+leave alone (and say so in the report) is a valid outcome.
+
+**STEP 2 — BROWSE the structure.**
+
+```
+memory_browse(query="<dominant candidate topic>")
+# → { index, hubs:[{path,title,pageType,snippet}], nearest:[…] }
+```
+
+One call shows you which hubs already exist and what each is about — decide whether a
+candidate cluster belongs under an EXISTING hub (attach, don't mint a duplicate hub) or
+needs a new one. Spot-check individual members with `memory_load` only where the title
+is ambiguous; do not load every page.
+
+**STEP 3 — DECIDE clusters (your LLM — this is the point).** Group the orphan leaves by
+topic. A cluster is a set of leaves that genuinely share one topic and deserve a single
+hub above them. For duplicate clusters, decide:
+
+- Same topic, one is a clear superset → **merge** (fold content, supersede the loser).
+- Adjacent but distinct → **link, don't merge** (write with `relation="related"` or a
+  typed `<a rel="related">` with a canonical href) — merging distinct facts loses recall
+  precision.
+- Ambiguous / high-stakes → **do not enact**; leave it for human review. When unsure,
+  prefer leaving two pages over deleting one.
+
+**STEP 4 — ENACT per cluster: promote WITH children.**
+
+```
+memory_curate(op="promote_to_hub",
+              pageId="<id of the cluster's natural anchor page>",
+              childPaths=["project/helios-billing.pkf",
+                          "project/helios-db-choice.pkf",
+                          "project/helios-deploy.pkf", …])
+```
+
+One call: the anchor becomes a hub AND every member is attached under it as a child.
+For a cluster that belongs under an EXISTING hub (found in STEP 2), don't promote —
+attach the members to that hub (`memory_write` the member with
+`parentHubPath="<existing hub path>"`; use `op="append-section"` rather than a
+full-page rewrite when touching someone else's page). For merge losers and garbage:
+`memory_curate(op="supersede", pageId="…", reason="…")`.
+
+**STEP 5 — REBUILD hub navigation once per batch.**
+
+```
+memory_curate(op="rebuild_index")
+```
+
+Each touched hub's strict PKF `#toc` regenerates with child descriptions. The top INDEX
+Contents changes automatically because it is a live graph projection—no INDEX body
+revision is minted. Leaves that now have a hub parent drop out of the flat top level.
+
+**STEP 6 — MAINTAIN authored prose (your editorial duty).** After the structure settles,
+read the INDEX and touched hubs. Refresh each hub's `<h2 id="overview">` and any stale
+authored INDEX semantic section. Reuse the loaded section's existing `data-sid`; for a
+new section, run `pkf_mint_sids`, then `pkf_validate` on the complete resulting page
+before persisting. Section-operation content is a complete `<section>…</section>`:
+
+```
+memory_write(
+  path="project/helios.pkf",
+  op="rewrite-section",
+  section="overview",
+  content="<section><h2 id=\"overview\" data-sid=\"<reuse-or-minted-sec-id>\">Overview</h2><p>Helios is the Q3 billing replatform —
+  auth, billing and deploy decisions live here; the postmortems under it record why
+  rate limits were re-tuned twice. Start at <a href=\"<canonical href from browse>\"
+  rel=\"references\">the API spec</a>.</p></section>")
+```
+
+A hub you just promoted has no overview yet — `op="append-section", section="overview"`
+seeds it. Never touch the `#toc` section while you are in there.
+
+**STEP 7 — VERIFY and REPORT.** Call `memory_curate(op="candidates")` again — the
+orphans you clustered should be gone. Then **report the structural changes in your
+reply**: which hubs you created/promoted, how many children each absorbed, what you
+superseded and why, which overviews you wrote/refreshed, which oversized advisories you
+split or deliberately left, and the before→after orphan count. A convergence run that
+ends without a structural report is unverifiable.
+
+### Worked example — 8 scattered `project/helios-*` leaves → one hub
+
+`candidates` returns 8 orphan leaves hanging off INDEX directly (`project/helios-auth.pkf`,
+`project/helios-billing.pkf`, `project/helios-db-choice.pkf`, `project/helios-deploy.pkf`,
+`project/helios-api-spec.pkf`, `project/helios-rate-limits.pkf`, `project/helios-oncall.pkf`,
+`project/helios-postmortem-0420.pkf`).
+
+```
+# 1-2. read candidates + browse — no existing helios hub, all 8 are one topic
+memory_curate(op="candidates", kind="orphans")
+memory_browse(query="helios project")
+
+# 3. decide: ONE cluster; helios-auth is the natural anchor
+
+# 4. promote the anchor WITH the other 7 attached in the same call
+memory_curate(op="promote_to_hub", pageId="<id-of-helios-auth>",
+              childPaths=["project/helios-billing.pkf", "project/helios-db-choice.pkf",
+                          "project/helios-deploy.pkf", "project/helios-api-spec.pkf",
+                          "project/helios-rate-limits.pkf", "project/helios-oncall.pkf",
+                          "project/helios-postmortem-0420.pkf"])
+
+#    the 0420 postmortem is superseded by a newer incident page → archive it
+memory_curate(op="supersede", pageId="<id-of-helios-postmortem-0420>",
+              reason="merged into project/helios-auth#incidents")
+
+# 5. rebuild once — hub #toc regenerates; INDEX Contents follows the graph live
+memory_curate(op="rebuild_index")
+
+# 6. seed the new hub's overview (the machine never writes this prose)
+memory_write(path="project/helios-auth.pkf", op="append-section", section="overview",
+             content="<section><h2 id=\"overview\" data-sid=\"<minted-sec-id>\">Overview</h2><p>Helios project knowledge —
+             auth is the anchor; billing/db/deploy/api-spec/rate-limits/oncall hang
+             under it. The 0420 postmortem is archived into #incidents.</p></section>")
+
+# 7. verify: orphans 8 → 0 for this topic; REPORT the delta in your reply
+memory_curate(op="candidates", kind="orphans")
+```
+
+Result: the derived INDEX Contents shows one described hub entry instead of 8 bare leaves; the facts
+are reachable `INDEX → hub → leaf`, and the hub opens with prose that says what lives
+there. The flat star collapsed into a readable tree — in ~7 tool calls.
+
+## Folding content on a merge
+
+When one page absorbs a true duplicate: copy any durable fact the survivor lacks into
+the survivor's matching section (`memory_write` with `op="append-section"` /
+`op="rewrite-section"` — never a whole-page rewrite of a page another agent authored;
+the section body follows `pkf-writing`), then `supersede` the loser with a reason naming
+the survivor's path. The loser is archived, not hard-deleted — it stays for audit and
+redirect.
+
+## Stop conditions
+
+- Enact only **clear** merges; one ambiguous call left un-enacted is better than one
+  wrong merge that destroys recall.
+- Batch a handful of clusters, `rebuild_index` ONCE, verify, report, stop. Do not loop
+  the whole graph every tick — Dream is incremental.
+- Never hand-write a hub `#toc`; `rebuild_index` is its only writer. Never store an
+  INDEX TOC copy—the reader derives Contents. Hub overviews and authored INDEX semantic
+  sections are your editorial territory.
+
+## Anti-patterns
+
+- ❌ Promoting a hollow hub (no `childPaths`) and then re-anchoring members one at a
+  time — pass the children in the promote call.
+- ❌ Hand-writing `child-of` links inside a HUB pointing down at leaves — `child-of`
+  edges point FROM the child TO the hub; the structural params get this right for you.
+- ❌ Hand-editing a hub `#toc`, or creating a stored INDEX `#toc`; declare edges +
+  `rebuild_index`. Leaving hubs with no overview prose is its own anti-pattern.
+- ❌ Treating message-inline/Asset PKF as a Dream candidate before it becomes an
+  authoritative Memory Page.
+- ❌ Whole-page-rewriting another agent's page to fold in one fact — append a section
+  (`op="append-section"`).
+- ❌ Treating an `oversized` advisory as an order — it is a split *suggestion*; splitting
+  a coherent hub just to satisfy a threshold destroys navigability. Judge, then report.
+- ❌ Merging two pages because they share a topic word — they may carry distinct facts.
+  Read them first; merge only clear duplicates.
+- ❌ Hard-deleting. You `supersede` (reversible archive), never destroy.
+- ❌ Running the whole graph every tick. Dream is incremental: a handful of clear
+  merges, one rebuild_index, verify, stop.
+- ❌ Enacting an ambiguous/high-stakes merge. Leave it for human review; Dream cannot
+  reconstruct a wrongly-merged page.
+- ❌ Retrying a `403 orchestrator_only` — you are not the appointed orchestrator; that
+  is correct, not an error.
+- ❌ A deputy assuming Dream rights because its bound member is the owner — the
+  deputy agent itself must be the appointed `orchestratorAgentId`.
+- ❌ Ending a convergence run without reporting the structural delta (hubs created,
+  children attached, pages superseded, orphan count before→after).

package/built-in-skills/memory-import/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: memory-import
+scope: common
+description: Bulk-import an external knowledge base into Prismer memory via the three-layer import pipeline (07 §3.1). Use when the user asks to import/migrate documents, a knowledge base, or notes into workspace memory. Layer 1 lands raw documents (zero LLM, instantly searchable); Layer 2 is YOUR distillation work — you read the landed documents and write candidate pages; Layer 3 commits candidates through the memory evolution gate. Distinct from the native memory_write tool face (that is for single, in-conversation writes).
+---
+
+# Memory Import
+
+Bulk-import external material into workspace memory through a **session** — the
+unit of quota, audit, and gate evaluation. Three layers, two of which are yours:
+
+## Layer 1 — land the documents (zero LLM, do this first)
+
+```bash
+cloud memory imports open --workspace <ws>          # → { id }
+cloud memory imports write-documents <id> --workspace <ws> --documents '[{"name":"…","content":"…"}]'
+```
+
+Raw documents become searchable in seconds. No quality bar here — that is Layer 2's job.
+
+## Layer 2 — distill (YOUR LLM, your compute)
+
+Read the landed documents, then author candidate pages and submit them:
+
+- One page per coherent topic, attached under the right hub (`<hub>/<topic>.pkf`, relative to the Memory root; do not prepend another `memory/`).
+- Every candidate MUST carry the `memory` frontmatter block — the pipeline rejects
+  the whole batch otherwise:
+  `{"type":"note","title":"…","description":"…","memory":{"memoryRole":"knowledge|procedure|action_result","source":"<where this came from, in words a human can read>"}}`.
+- Distill, don't dump: conclusions and procedures, not transcripts. The raw
+  documents stay in Layer 1 as the reference layer.
+
+```bash
+cloud memory imports write-batch <id> --workspace <ws> --candidates '[{"pagePath":"…","contentDiff":"<full PKF body>"}]'
+```
+
+## Layer 3 — commit (cloud-side gate, zero negotiation)
+
+```bash
+cloud memory imports commit <id> --workspace <ws>   # runs the evolution gate
+cloud memory imports status <id> --workspace <ws>   # per-candidate verdicts
+```
+
+The gate REJECTS batches that lose retrieval coverage (a candidate replacing a
+page must not delete its keywords) or lack metadata. A rejected commit is final
+for the session: read the verdict, fix the candidates, open a NEW session, resubmit.
+Never re-submit an identical rejected batch — the Ledger rejects same-shape
+candidates for 30 days.
+
+**Routing**: raw archive / small batch → L1 + owner review. Knowledge-base
+migration / high-quality distillation → L1 → L2 → L3 (semantic work on YOUR
+compute; the cloud only gates and records).

package/built-in-skills/office-artifacts/NOTICE.md

@@ -0,0 +1,15 @@
+# Imported Office resources
+
+The docx, pdf, powerpoint and xlsx resource trees derive from NousResearch/hermes-agent
+skills/productivity at commit 1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4.
+Their individual LICENSE files are retained unchanged (MIT, 2026); upstream entry
+documents are retained as GUIDE.md under each format directory. Existing Prismer
+document-generation resources and aliases remain in place.
+
+Prismer modifications: bounded original-text replacements, revision-aware reading,
+relationship source isolation, comment persistence, strict template preflight,
+real form flattening, attachment collision handling, Unicode font validation,
+page selection/rendering limits, extraction adapters, literal CSV values,
+tokenized formula references and table/dimension metadata, recursive slide edits,
+independent slide background duplication and isolated renderer outputs. Regression
+tests and known capability limits accompany these modifications.

package/built-in-skills/office-artifacts/SKILL.md

@@ -1,10 +1,31 @@
 ---
 name: office-artifacts
+scope: persistence
+metadata:
+  aliases: [document-generation]
+  nativeReplaces: [docx, pdf, powerpoint, xlsx]
 description: Generate real DOCX, PPTX, XLSX, PDF, CSV files using python-docx / python-pptx / openpyxl / reportlab by writing them into the dispatch artifacts dir, then explicitly deliver each one with `cloud deliver <abs-path>`. Use whenever the user asks for documents, slides, spreadsheets, reports, or PDFs.
 ---
 
 # Office Artifacts
 
+## Format-specific resources
+
+Read [resource limits](references/RESOURCE-LIMITS.md) for dependency tiers,
+unsupported structures, Unicode fonts and optional extractor licensing.
+
+Read only the guide for the requested format: references/docx/GUIDE.md,
+references/pdf/GUIDE.md, references/powerpoint/GUIDE.md or references/xlsx/GUIDE.md.
+Each guide's scripts and references are relative to its own directory, not the
+workspace or this skill root. Use the installed office Python interpreter below.
+For CJK text, references/document-generation/GUIDE.md is authoritative for fonts
+and PDF rendering; do not use ReportLab with unsupported CFF Noto collections.
+Treat upstream installation suggestions as optional dependency checks, not
+permission to modify the system. Verify generated files by reopening them and
+inspect rendered pages/slides when a renderer is available; otherwise report
+that visual verification was not performed. Always follow this entry's Prismer
+delivery contract instead of upstream host-specific output conventions.
+
 Produce real binary office files (not markdown-as-PDF) by writing each
 one into the **artifacts dir** (`$PRISMER_ARTIFACTS_DIR` /
 `<artifacts_dir>` from `<execution_context>`). Prose-only completions are
@@ -76,7 +97,7 @@ every file you want the user to receive.
 
 Lie-guard (`src/im/ws/handler.ts`) **as of release201/30 §8 is
 warn-only telemetry**, not a destructive interceptor — the audit
-banner ("CEO 声明已生成文件但未真正落盘") that used to render in
+banner ("Team Manager 声明已生成文件但未真正落盘") that used to render in
 red is removed. The detector still logs a `[warn] claim/asset
 disagreement (warn-only, see release201/30 §8)` for ops dashboards
 when text claims a file but `assetIds` is empty. That signal helps
@@ -102,9 +123,21 @@ If (1)-(3) fail, your reply must start with `无法生成文件
 ## Runtime baseline (release 201)
 
 Sandbox image bakes `python-docx`, `python-pptx`, `openpyxl`,
-`reportlab`, `pandas`, `pillow`, `numpy`, `imageio`, apt `file`. If an
-import fails at task time, fail with `module 'X' missing — rebuild
-sandbox image`. Do not `pip install` on the fly.
+`reportlab`, `pandas`, `pillow`, `numpy`, `imageio`, apt `file` — all of
+them inside the image venv interpreter **`/home/user/.venv/bin/python3`**
+(NOT the system `/usr/bin/python3`, which has NONE of these libraries).
+Always run generator scripts with that interpreter, e.g.
+
+```bash
+/home/user/.venv/bin/python3 generate_report.py
+```
+
+If an `import docx` (or `pptx` / `openpyxl` / `reportlab`) probe fails, DO
+NOT conclude the dependency is missing until you have retried under
+`/home/user/.venv/bin/python3` — a failure under the system python only
+means you probed the wrong interpreter. Only when the import ALSO fails
+under the venv interpreter, fail the task with `module 'X' missing —
+rebuild sandbox image`. Do not `pip install` on the fly.
 
 ## Resolving the output directory
 

package/built-in-skills/office-artifacts/references/RESOURCE-LIMITS.md

@@ -0,0 +1,44 @@
+# Imported resource execution contract
+
+Use absolute script paths relative to the chosen format GUIDE.md directory.
+Never install packages into the shared runtime merely because an upstream guide
+includes an installation command. Reopen outputs and inspect rendered pages before
+claiming visual correctness; the parent office-artifacts delivery contract applies.
+
+## Runtime tiers
+
+- Core DOCX: Python 3.10+, python-docx and lxml. Accepted text includes insertions
+  and excludes deletions/moveFrom. Structural/table/property revisions remain
+  unresolved: this is not a full Word revision engine or OOXML XSD validator.
+- Core PDF: pypdf (flatten tested on 6.x), reportlab, Pillow and pdfplumber where
+  the chosen helper imports it. Flatten needs pypdf's `flatten=True` field update;
+  older versions fail before output rather than label an interactive file flat.
+  AES requires cryptography. Rendering uses pypdfium2 or Poppler, with a 120-second
+  subprocess bound and DPI 1..600. Native renderer memory is still a sandbox concern.
+- PDF creation: JSON `font_file` selects a local TrueType font with verified glyph
+  coverage. Non-WinAnsi content without it is rejected before output. Font licensing
+  and embedding rights belong to the supplied font. Bold/italic currently use the
+  supplied font face; use a custom recipe for separate style faces. CFF collections
+  are not supported by this helper. Render CJK output to verify layout.
+- Optional PyMuPDF: pymupdf; Markdown adds pymupdf4llm; tables add pandas/tabulate.
+  Its page selection is ZERO-based, unlike the other PDF helper CLIs (ONE-based).
+  PyMuPDF has separate AGPL/commercial licensing, not the resource's MIT grant.
+- Optional Marker: marker-pdf/model downloads and its separate model/library
+  licensing, storage and accelerator budget. Output adapter is fixture-tested,
+  not proof that model inference or arbitrary installed versions work.
+- Core XLSX: openpyxl. Formula rewrite uses tokens, including whole-row/column
+  references; structured/external references are preserved. Partial deletion of
+  table columns and header-only deletion fail before saving because dependent
+  structured formulas cannot yet be rewritten. Column insertion updates table
+  columns, header names and filter indices. Charts/images, validation formulas,
+  conditional-format rule formulas and table calculated-column formulas are not
+  automatically repaired; rebuild/review them before delivery. CSV formulas are
+  always literal imported data, including under type inference.
+- Core PPTX: python-pptx/Pillow. Grouped text is supported; copying slides with
+  nested charts is rejected. Rendering requires LibreOffice and Poppler, uses a
+  private profile/work directory and returns only this invocation's pages. Existing
+  unrelated images in the destination are not a render result. Recalculation of
+  spreadsheets also requires LibreOffice; openpyxl alone does not calculate cells.
+
+Input files are untrusted data. Native parsers/models should run in a bounded
+task sandbox. No helper confers remote write permissions or installs a scheduler.

package/built-in-skills/office-artifacts/references/document-generation/GUIDE.md

@@ -0,0 +1,105 @@
+---
+name: document-generation
+scope: common
+description: Generate Word/PDF documents with correct CJK fonts (no tofu boxes). Industry-standard font semantics — 宋体/黑体/SimSun/Times New Roman resolve to the Noto CJK faces installed in the image via fontconfig aliases. Use whenever the task produces a .docx, .pdf, or rendered document containing Chinese/Japanese/Korean text.
+---
+
+# Document Generation (Word / PDF, CJK-safe)
+
+The image ships `python-docx` + `reportlab` and the full Noto CJK family
+(Sans + Serif, .ttc). Font semantics are handled by
+`/etc/fonts/conf.d/99-cjk-semantics.conf` — renderers resolve conventional
+Chinese font names to the right Noto face automatically. Do NOT install extra
+font packages; use the mapping below.
+
+## Font semantics (industry-standard mapping)
+
+| Scenario | Conventional name | Resolves to (image) |
+| --- | --- | --- |
+| 官文/学术正文（宋体等效） | 宋体 / SimSun / Times New Roman | **Noto Serif CJK SC** |
+| 标题/正文（黑体等效） | 黑体 / SimHei | **Noto Sans CJK SC** |
+| 楷体（无开源 Noto 楷体，Serif 兜底） | 楷体 / KaiTi / 仿宋 | Noto Serif CJK SC |
+| 代码/等宽 | Courier New / Monospace | DejaVu Sans Mono + Noto fallback |
+
+Rule of thumb: **serif (Noto Serif CJK SC) for official/academic documents,
+sans (Noto Sans CJK SC) for UI/headings** — same convention as Times New Roman
+vs Arial in Western docs.
+
+## Word (.docx) — python-docx
+
+Word stores font *names*, not glyphs — the rendering machine resolves them.
+Two cases:
+
+**A. User opens the docx on their desktop (Word/WPS has 宋体/SimSun)** — write
+conventional names so it renders correctly on THEIR machine:
+
+```python
+from docx import Document
+from docx.shared import Pt
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+
+doc = Document()
+# set east-asian font properly (both ascii + eastAsia, or Word ignores it):
+style = doc.styles['Normal']
+style.font.name = 'Times New Roman'          # ascii
+style.font.size = Pt(12)
+style.element.rPr.rFonts.set('{http://schemas.openxmlformats.org/wordprocessingml/2006/main}eastAsia', '宋体')
+p = doc.add_paragraph('中文正文——宋体五号')
+doc.save('/workspace/output.docx')
+```
+
+**B. The sandbox itself must render/convert the docx to PDF** — use Noto names
+so fontconfig resolves locally (LibreOffice may not be installed; prefer
+generating PDF directly with reportlab instead of converting).
+
+## PDF — weasyprint (HTML→PDF, PREFERRED — industry standard for CJK)
+
+**reportlab cannot render Noto CJK** (CFF/PostScript outlines — a reportlab
+limitation, verified 2026-08-07). The industry-standard CJK PDF path is
+**HTML/CSS → weasyprint**: CSS font-family resolves via fontconfig, the
+aliases make conventional names work directly, and it ships in the image.
+
+```python
+from weasyprint import HTML
+
+html = '''<html><head><style>
+  body { font-family: '宋体', 'Noto Serif CJK SC', serif; font-size: 12pt; }
+  h1   { font-family: '黑体', 'Noto Sans CJK SC', sans-serif; }
+  code { font-family: 'Courier New', monospace; }
+</style></head><body>
+<h1>中文标题——黑体</h1>
+<p>中文正文——宋体等效。混合 ASCII text works too.</p>
+</body></html>'''
+HTML(string=html).write_pdf('/workspace/output.pdf')
+```
+
+pandoc is also present — `pandoc input.md -o output.pdf
+--pdf-engine=weasyprint` is a valid markdown→PDF pipeline.
+
+## PDF — reportlab (programmatic; ASCII/Latin only for CJK)
+
+reportlab 5.0 rejects Noto CJK .ttc files (`postscript outlines are not
+supported` — CFF outlines). Use reportlab only for Latin/ASCII documents, or
+for PDFs whose text never contains CJK. For CJK content use weasyprint above.
+
+```html
+<style>
+  body { font-family: '宋体', 'Noto Serif CJK SC', serif; font-size: 12pt; }
+  h1   { font-family: '黑体', 'Noto Sans CJK SC', sans-serif; }
+</style>
+```
+
+## Verification
+
+```bash
+fc-match '宋体'     # → Noto Serif CJK SC (alias working)
+fc-match '黑体'     # → Noto Sans CJK SC
+fc-list | grep -c 'Noto.*CJK'   # faces present
+```
+
+## Output contract
+
+- Deliver the file as a task asset (`cloud file send` / attach) — never paste
+  document content as chat text.
+- Verify the PDF opens (pdfplumber is installed) and contains the expected
+  Chinese text — tofu boxes are a FAIL, not a delivery.