From e2098e73711099a2b01e201ade43881224eb27c5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E6=98=9F=E6=9C=88?= <xingyue@shazhou.work>
Date: Tue, 2 Jun 2026 23:59:07 +0800
Subject: [PATCH] docs: update stale comments and prompts referencing old
 storage formats
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- architecture-reference.ts: threads.yaml/history.jsonl/registry.yaml → variable store, storage layout updated (~/.ocas/ + ~/.uwf/)
- protocol types.ts: JSDoc comments updated
- thread-index.ts: serialization comment updated
- util-agent context.ts: buildContext JSDoc updated

Only migration code in store.ts retains old file references (needed to read legacy files).
---
 packages/protocol/src/thread-index.ts       |  2 +-
 packages/protocol/src/types.ts              |  4 ++--
 packages/util-agent/src/context.ts          |  2 +-
 packages/util/src/architecture-reference.ts | 14 ++++++++------
 4 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/packages/protocol/src/thread-index.ts b/packages/protocol/src/thread-index.ts
index 5fcf7d9..91daaaf 100644
--- a/packages/protocol/src/thread-index.ts
+++ b/packages/protocol/src/thread-index.ts
@@ -50,7 +50,7 @@ export function markThreadSuspended(
   };
 }
 
-/** Serialize for threads.yaml — compact string when not suspended. */
+/** Serialize for variable store — compact string when not suspended. */
 export function serializeThreadIndexEntry(
   entry: ThreadIndexEntry,
 ): string | Record<string, string> {
diff --git a/packages/protocol/src/types.ts b/packages/protocol/src/types.ts
index f1c4264..82b39f7 100644
--- a/packages/protocol/src/types.ts
+++ b/packages/protocol/src/types.ts
@@ -113,7 +113,7 @@ export type StepOutput = {
   background: boolean | null;
 };
 
-/** Active thread entry in ~/.uwf/threads.yaml */
+/** Active thread entry in @uwf/thread/* variable store */
 export type ThreadIndexEntry = {
   head: CasRef;
   suspendedRole: string | null;
@@ -210,5 +210,5 @@ export type WorkflowConfig = {
   modelOverrides: Record<Scenario, ModelAlias> | null;
 };
 
-/** ~/.uwf/threads.yaml */
+/** @uwf/thread/* variable store index */
 export type ThreadsIndex = Record<ThreadId, ThreadIndexEntry>;
diff --git a/packages/util-agent/src/context.ts b/packages/util-agent/src/context.ts
index 3e6cf40..7301f4d 100644
--- a/packages/util-agent/src/context.ts
+++ b/packages/util-agent/src/context.ts
@@ -150,7 +150,7 @@ async function loadWorkflow(store: Store, schemas: AgentStore["schemas"], workfl
 }
 
 /**
- * Build agent execution context from thread head in threads.yaml.
+ * Build agent execution context from thread head in the variable store.
  * Walks the CAS chain from head to StartNode and expands step outputs.
  */
 export async function buildContext(
diff --git a/packages/util/src/architecture-reference.ts b/packages/util/src/architecture-reference.ts
index dbe9ab2..df903df 100644
--- a/packages/util/src/architecture-reference.ts
+++ b/packages/util/src/architecture-reference.ts
@@ -15,7 +15,7 @@ Stored artifacts include:
 ### Thread
 A Thread is a single execution of a Workflow, identified by a ULID (26-char Crockford Base32: 10 timestamp + 16 random). Thread state is an immutable CAS chain — each step points to its predecessor via a \`prev\` hash, forming a linked list.
 
-Active threads are indexed in \`threads.yaml\`; completed threads move to \`history.jsonl\`.
+Active threads are indexed as \`@uwf/thread/*\` variables; completed threads move to \`@uwf/history/*\` variables in the ocas variable store.
 
 A thread progresses by running \`uwf thread exec\`, which performs one moderator→agent→extract cycle per step.
 
@@ -51,10 +51,12 @@ uwf thread exec <thread-id>
 
 ## Storage Layout
 
-All data lives under \`~/.uwf/\`:
-- \`cas/\` — content-addressed store (XXH64-keyed)
-- \`threads.yaml\` — active thread index
-- \`history.jsonl\` — completed thread archive
-- \`registry.yaml\` — workflow name → CAS hash mapping
+CAS data lives under \`~/.ocas/\`:
+- \`objects/\` — content-addressed store (XXH64-keyed)
+- \`variables.db\` — variable store (\`@uwf/registry/*\`, \`@uwf/thread/*\`, \`@uwf/history/*\`)
+
+Config lives under \`~/.uwf/\`:
+- \`config.yaml\` — provider, model, agent settings
+- \`.env\` — API keys
 `;
 }
-- 
2.43.0