@bizagent/dsh 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+## 1.0.0 — 2026-10-20
+
+The first stable release: everything since `0.1.0-alpha.2`.
+
+### Native DSH integration and onboarding
+
+- Reorganize the READMEs around installation, first success, daily use, and references. Add a
+  concise Chinese install guide and a six-step delivery walkthrough, with UI locations, success
+  checks, and separate examples for the 300 and 400.50 GMV datasets. Record the tested DSH
+  version and verification scope.
+- Move the organization workbench into DSH's native sidebar/main-panel navigation. Home,
+  Project, and memory links open the corresponding record and preserve the Session context.
+- Add Session Home actions, an unread Inbox count, sidebar Session identities and Home actions,
+  a **Work & learning** conversation view, and completed-turn receipts backed by successful
+  durable tool results. Show live Agent runtime separately from recorded Work status.
+- Resolve selected `@Agent` Homes at DSH's pre-step admission boundary and log their bounded
+  snapshots before model calls. Loading failures are explicit; cancelled admission can be retried
+  without assuming an unlogged snapshot was delivered. Hide transport markers from user text.
+- Share browser requests across Session surfaces and cancel abandoned loads.
+
+### Runs on DSH 0.2
+
+- Installation, development dependencies, and runtime CI pin DSH `0.2.1-rc.2`. DSH peers require
+  `^0.2.1-rc.2`. CI also checks selected Frame admission and Session Work/result surfaces.
+  DSH 0.2 skips plugins whose DSH peers
+  name another line, so 0.1 builds no longer load.
+- Sessions that BizAgent starts (Principals, Project Mains, Work workers, Inbox wake-ups, learning
+  reviews) join DSH's default agent preset and use the host's default model. Without the model,
+  resumed sessions failed every turn on DSH 0.2.
+- Chats opened from the panel are attached to a workspace named after their Home and appear in the
+  DSH sidebar.
+
+### Organization folders and the personal Home
+
+- BizAgent keeps its data in `~/BizAgent` (or `$BIZAGENT_HOME`) instead of `$DSH_HOME/bizagent`.
+  Your personal Homes live there; each organization gets its own folder, `orgs/<id>/`, which BizAgent
+  adds to the top of the DSH sidebar. Setup no longer asks for a DSH workspace. Data at the old
+  default place keeps being used until you move it, and organizations already created inside a
+  workspace keep working where they are (`active-organization.yaml` format 1 still loads; new ones
+  are format 2).
+- Sessions outside the organization folder belong to your personal Home (`personal:default`), which
+  now exists with or without an organization. Before, they fell back to the organization's business
+  Home, so unrelated work (coding in your own repositories) was saved into the organization's
+  memory. Such bindings from earlier versions are released at startup.
+- File copies kept for Worklogs, Work, Projects, and learning reviews go to the data folder of the
+  Home they belong to, so personal work never lands in the organization folder.
+- The panel shows which Home the current chat belongs to, offers **New chat in organization** for
+  personal chats, groups the Home list into your Homes and the organization's, and shows the
+  Learning view even before an organization exists.
+- Your personal Home shows as *My personal Home* in the panel instead of its address.
+
+### Works out of the box
+
+- **Create sample team** in first-time setup builds *Sample Shop* (a growth lead, a data analyst,
+  a metric capability, and a small `orders.csv`) with a five-minute guide on the Organization page.
+- The local person owns the Homes BizAgent creates (`owner` option; defaults to
+  `BIZAGENT_LOCAL_HUMAN_ID` or the OS user name). Before, the default Home had no owner and
+  onboarding organizations were owned by member ids, so nobody could accept their results.
+- In DSH Web the person signed in to DSH is the reviewer: accepting a Project, deciding proposals,
+  and reading My Inbox need no BizAgent token. A Bearer token file remains for scripts.
+- Formal Work and Inbox wake-ups start in the assignee Home's own folder when no `workspaceHomes`
+  mapping exists, so teammates created in the UI pick up handed-off work.
+- `timeZone` option for cron schedules and daily limits (default: the host time zone) instead of
+  fixed Asia/Shanghai time.
+- Project results, assets, proposals, Worklogs, and mail in the panel are rendered as Markdown
+  with DSH's own renderer instead of raw text.
+- A Work result or reply that reaches a Session still working is read at its next step. Before, it
+  waited for the next turn, so a Project chat that had already handled the result ran one more turn.
+
+### Safer
+
+- Every BizAgent HTTP route requires DSH Web's login when DSH provides it, in addition to the
+  loopback, cross-site, and same-origin checks. Cross-owner Work never starts on its own.
+- Text from other Homes reaches the model fenced as data. Evidence reads stay within the
+  session's own Home. Snapshots of files are read without following symlinks.
+- Session and record ids are scoped to the session and its tool call, so parallel and replayed
+  calls cannot collide. One damaged record or Home file is isolated instead of stopping startup.
+
+### Smaller and clearer
+
+- The package keeps the learning core, Inbox, formal Work, and a narrowed Project loop (create,
+  invite, join, submit, rework, human acceptance). Internal integrations from earlier development
+  were removed; 59 Agent tools remain.
+- The main entry exports only the DSH plugin and its types. Building blocks for hosts with their
+  own login moved to `@bizagent/dsh/host`.
+- Tool results are compact JSON, and Project and Work reads return summaries.
+- English documentation: quick start, concepts, configuration, architecture, and a tool
+  reference generated from the code. License changed to MIT.
+
+## 0.1.0-alpha.2
+
+- 新增首次组织设置：使命、团队模板、成员/角色与共享能力可在一个流程中确认并批量创建；
+- 新增 `organization.yaml` 关系清单和组织图，Organization 作为四类 Home 之上的容器，而不是第五类 Home；
+- UI 重构为“组织 / 学习”双视图，组织图可直接进入各责任主体的学习账本；
+- Home 创建改为临时目录完整写入后原子 rename；组织清单只在全部引用 Home 存在后提交，失败可幂等重试；
+- Home Context 改为 `agent.inject()` 持久 Snapshot，同一 Session/Revision 不重复注入，支持重启与 replay；
+- 新增只针对明确纠正的有界 Learning Checkpoint，普通 Turn 不增加模型调用；
+- Checkpoint 以 `Session + Turn` 确定性编号并幂等结算，复用现有 metadata 表而不改变 Storage Domain 版本；
+- 新增 `bizagent_evidence_read`，可以回读资产引用的有界 DSH Session 事件；
+- 调整 Fitness：retrieved/applied 不自证有效，两次 contradicted/failed 后提示人工复查；
+- 保持 Learning Trigger 接口独立，后续业务插件可增加自己的强信号检测器。
+
+## 0.1.0-alpha.1
+
+- 新增 DSH 原生 Web Client 插件，通过 sidebar 与 shell overlay slot 挂载组织记忆台；
+- 新增 Home directory、Memory strata、Learning ledger、证据详情和 Proposal inbox；
+- 新增创建 Home 与目标 owner proposal 裁决交互，不开放无 evidence 的直接 Memory 写入；
+- UI Host adapter 作为独立 Cordis row，通过有 body 上限、no-store 和同源 mutation 检查的 HTTP API 提供数据；
+- Client bundle 与 learning kernel 完全分离，核心代码不依赖 React；
+- 在 DSH `0.1.1-rc.2` 中验证 Client 启动图、bundle serving、API 读取、同源写入和跨源拒绝。
+
+## 0.1.0-alpha.0
+
+首个可运行版本：
+
+- 作为 DSH Cordis Bundle 安装，不 fork DSH、不另起 daemon；
+- 实现 Personal、Business、Role、Capability 四类 Agent Home；
+- 实现有界 Home Context、多级学习资产与跨 Session 持久化；
+- 实现带当前 DSH turn 证据的 Memory 写入、更新、检索和 fitness feedback；
+- 实现跨 Home proposal、owner 审批、幂等接受/拒绝和恢复对账；
+- 提供 10 个 DSH tools 以及 `init`、`home`、`doctor`、`reindex` CLI；
+- 通过单元、插件集成、tarball 安装及 DSH `0.1.1-rc.2` Web profile 启动验证。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BizAgent contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# @bizagent/dsh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Long-term memory and teamwork for agents on [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness).
+
+BizAgent adds lasting Homes, evidence-backed learning, governed sharing, Inbox messages, formal
+Work, and Projects with human acceptance. DSH runs the models, tools, and sessions.
+
+## Start here
+
+- **Install:** [English quick start](docs/quickstart.md) / [中文安装指南](docs/quickstart.zh-CN.md).
+- **Already installed:** [use BizAgent](docs/quickstart.md#use-bizagent) / [中文用户指南](docs/user-guide.zh-CN.md).
+- **Look up a feature:** [documentation map](docs/README.md), [concepts](docs/concepts.md),
+  [configuration](docs/configuration.md), [59 Agent tools](docs/tools.md).
+- **Check versions and evidence:** [verification and compatibility](docs/verification.md).
+
+Start with one saved rule in your personal Home. An organization is optional for that first step;
+existing organizations can use separate practice Homes without resetting data.
+
+## In DSH Web
+
+| Surface | Use |
+| --- | --- |
+| BizAgent organization panel | Organize Homes; inspect learning; review proposals and Projects |
+| Session Home button | Check which Home owns the conversation and open its learning |
+| Work & learning tab | Inspect this session's Work, worker/result links, and related Projects |
+| Turn receipts | Open the successful records saved in a completed turn |
+| Composer `@` and Frame bar | Load shared Home context in the current session |
+| My Inbox | Read agent messages and reply to the originating session |
+
+Formal Work starts in an independent worker when both Homes share an owner. A Frame provides
+read-only context in the current session. Only a person can accept a submitted Project result.
+
+## Package entry points
+
+| Import | Use |
+| --- | --- |
+| `@bizagent/dsh` | Core plugin and types (`name`, `inject`, `Config`, `apply`) |
+| `@bizagent/dsh/ui-host` | Authenticated panel HTTP routes |
+| `@bizagent/dsh/local-human-host` | Local owner's review and Inbox routes |
+| `@bizagent/dsh/client` | Browser bundle loaded by DSH Web |
+| `@bizagent/dsh/host` | Building blocks for hosts with their own authentication |
+
+The package also installs `bizagent` for Home files: `init`, `home create|list`, `doctor`,
+`reindex`, and `archive export|verify|import`. Run `bizagent --help` for usage.
+
+## Development
+
+```sh
+npm ci
+npm test                 # builds and runs automated tests
+npm run typecheck
+npm run examples         # service scenarios without a model
+npm run smoke:local-human
+npm run smoke:session-ui
+npm run pack:check
+```
+
+Runtime smokes use isolated profiles and a local fake model. See [verification](docs/verification.md)
+for the distinction between service tests, runtime integration, and real-model browser acceptance.
+For user-visible changes, update the [changelog](CHANGELOG.md).
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# BizAgent v0.1 requires the DSH Web profile's ctx.storageDomain service.
+# The row is inserted after the standard bundles and remains user-patchable.
+- insert:
+    - id: bizagent
+      name: '@bizagent/dsh'
+      config:
+        defaultHome: 'personal:default'
+        autoCreateDefaultHome: true
+        identityMaxBytes: 6144
+        indexMaxBytes: 16384
+    - id: bizagent-ui
+      name: '@bizagent/dsh/ui-host'
+    - id: bizagent-local-human
+      name: '@bizagent/dsh/local-human-host'

package/docs/README.md

@@ -0,0 +1,23 @@
+# 文档导航 / Documentation
+
+按当前任务选择一页即可，不需要从头读完所有文档。
+Choose the page for your task; the reference pages are optional.
+
+| 任务 / Task | 中文 | English |
+| --- | --- | --- |
+| 安装插件，确认第一次成功 / Install and verify | [快速开始](quickstart.zh-CN.md) | [Quick start](quickstart.md) |
+| 使用界面，完成记忆、派工和验收 / Use the product | [用户指南](user-guide.zh-CN.md) | [Quick start: use BizAgent](quickstart.md#use-bizagent) |
+| 理解 Home、Frame、Inbox、Work、Project / Understand the model | [用户指南中的选择表](user-guide.zh-CN.md#该用哪种协作方式) | [Concepts](concepts.md) |
+| 核对版本与已验证范围 / Check compatibility and evidence | [版本说明](quickstart.zh-CN.md#安装) | [Verification](verification.md) |
+| 调整模型、目录或计划 / Configure | [模型入口](quickstart.zh-CN.md#连接模型并启动) | [Configuration](configuration.md) |
+| 研究接入和权限边界 / Integrate | — | [Architecture](architecture.md) |
+| 查询具体工具参数 / Look up a tool | — | [Generated tool reference](tools.md) |
+
+**建议路线**：安装 → 保存一条规则 → 新会话读取 → 独立派工 → 人工验收。
+**Suggested route**: install → save a rule → recall in another session → dispatch Work → accept the Project.
+
+已有 DSH 时跳过安装 DSH；已有组织时跳过首次组织设置。
+问题排查放在[快速开始](quickstart.zh-CN.md#遇到问题时)末尾；数据目录和备份边界见[配置](configuration.md#data-and-backups)。
+
+For contributors: [development and checks](../../../CONTRIBUTING.md),
+[Learning Lab](../examples/README.md), [changelog](../CHANGELOG.md).

package/docs/architecture.md

@@ -0,0 +1,154 @@
+# Architecture and trust model
+
+BizAgent is a set of DSH plugins. It does not run its own agent loop, server, or database: DSH runs
+every session, calls the model, executes tools, and stores conversations; BizAgent adds Homes,
+learning, and the records that connect agents.
+
+## Components
+
+| Plugin row | Module | Does |
+| --- | --- | --- |
+| `bizagent` | `@bizagent/dsh` | The core: binds sessions to Homes, adds the system prompt section, the Home snapshot, and the Agent tools, and runs Work, Inbox wake-ups, and learning reviews. |
+| `bizagent-ui` | `@bizagent/dsh/ui-host` | HTTP routes for the BizAgent panel. |
+| `bizagent-local-human` | `@bizagent/dsh/local-human-host` | Review routes for the local owner: Project acceptance, proposal decisions, My Inbox. |
+| (browser) | `@bizagent/dsh/client` | Native organization panel, Session Home actions, Work & learning view, sidebar decorations, turn receipts, `@` references, and the Frame bar. |
+
+The core needs these DSH services: `agents`, `tools`, `systemPrompt`, `storageDomain`,
+`sessionQuery`, and `agentDefaultModel`. See [Verification](verification.md) for the development
+baseline and separately tested DSH Web runtime.
+
+```mermaid
+flowchart LR
+    DSH[DSH sessions and tools] --> Core[bizagent core]
+    Core --> Files[Home folders: identity and assets]
+    Core --> Ledgers[DSH storageDomain: bindings, proposals, Inbox, Work, Projects, Worklogs]
+    Sessions[DSH sessionQuery: conversations] --> Core
+    Core --> Snapshot[Home snapshot at session start]
+    Snapshot --> DSH
+    Panel[BizAgent panel] --> Routes[ui-host and local-human-host routes]
+    Routes --> Core
+```
+
+## Where data lives
+
+| Data | Stored in | Notes |
+| --- | --- | --- |
+| Homes: identity, assets, revisions | Home folders, as Markdown and YAML | Organization Homes inside `~/BizAgent/orgs/<id>/`, personal Homes in `~/BizAgent` (`homeRoot`). Written atomically; one bad file isolates its Home instead of stopping startup. |
+| Organization structure | `organization.yaml`, `directory.yaml` | `directory.yaml` records each Home's owner, so editing `home.yaml` cannot change ownership. |
+| Which organization is active | `homeRoot` | `active-organization.yaml`, naming the organization folder. |
+| Session bindings, Frames, proposals, receipts, Inbox, learning reviews | DSH `storageDomain`, domain `bizagent` | Versioned records validated on read. |
+| Formal Work, Projects, Worklogs | DSH `storageDomain`, their own domains | Frozen copies of their files are kept in the data folder of the Home they belong to: the organization folder, or `homeRoot` for personal Homes. |
+| Conversations | DSH sessions | Assets point at session events as evidence. |
+
+Only one DSH process may run BizAgent against the same data: startup takes a writer lock on
+`$DSH_HOME`, `homeRoot`, and the organization folder, and a second process skips BizAgent with
+"BizAgent writer is already reserved". A lock left by a crashed process is recovered on the next
+start.
+
+Backups need both halves: the Home folders (`bizagent archive export`, which records a digest of
+every file) and DSH's own data directory.
+
+## A session, step by step
+
+1. DSH creates or resumes a session. BizAgent resolves its Home from the working directory and
+   records the binding once.
+2. BizAgent adds a Home snapshot (identity plus the index of active assets) and, if mail is
+   waiting, an Inbox digest. Both are skipped when the session already holds the current version.
+   A failure here never blocks the session; it is reported in the panel's health status.
+3. At DSH's `agent/pre-step` boundary, selected `@Agent` references are revalidated and resolved
+   into logged, bounded Home snapshots before the model request. Transport markers are removed
+   from the admitted user text. A failed load produces an explicit notice. A retry loads a full
+   snapshot again so cancelled admission cannot leave the model relying on an unlogged copy.
+4. The agent works. BizAgent tools read and write only the bound Home, except through proposals,
+   Inbox messages, Work, and Projects.
+5. At the end of a turn with an explicit correction, BizAgent asks the agent once to decide
+   whether to keep it.
+6. When the turn is saved, BizAgent records a Worklog for turns that used tools.
+
+## Native DSH surfaces
+
+The organization workbench occupies DSH's keyed `main` panel and has a `sidebar.panellist`
+entry. It shares navigation with the host instead of covering it with an application-wide modal.
+The current Session remains available when returning to the conversation.
+
+Session headers expose the bound Home, candidate/proposal counts, and My Inbox. The
+`conversation.view` entry **Work & learning** shows Work directly dispatched from or assigned to
+this exact Session, related Projects, and successful BizAgent tool results. Sidebar row decorations,
+hover details, and a context-menu action identify Principals, Project Mains, workers, Inbox wakes,
+and learning reviews. `conversation.chat.turnTail` shows receipts from the original completed turn.
+An unfinished or failed tool call cannot produce a success receipt. Historical receipt status is
+labelled separately from the current Work record. Runtime status is read from live DSH Agents;
+an accepted Work does not imply a running worker.
+
+Authenticated `/api/bizagent/v1/sessions` supplies a lightweight catalog without opening Session
+logs or creating bindings. `/api/bizagent/v1/session-context` resolves one existing Session using
+the same live/persisted lookup and trust checks as the Frame API. Browser readers share requests,
+abort abandoned loads, stop polling when unobserved, and pause polling in hidden tabs. The Work
+view shows the latest 20 Work records and the latest 100 successful activity records.
+
+Sessions that BizAgent starts itself (Work workers, Inbox wake-ups, learning reviews, Principals,
+Project Mains) join DSH's default agent preset, so they have the same built-in tools as sessions
+you open, and use the host's current default model.
+
+Opening a worker from the Work view uses the authenticated agent-session route to reveal an
+already bound, locally owned Session in its Home Workspace. It does not recreate or start its
+Agent, and ordinary conversations keep their existing Workspace. For the user path, see the
+[quick start](quickstart.md#use-bizagent) or [Chinese user guide](user-guide.zh-CN.md).
+
+## Trust model
+
+BizAgent is built for **one person on one machine**. It keeps agents honest about whose Home they
+write to; it is not a sandbox.
+
+What BizAgent enforces:
+
+- **Tools act as the session's Home.** No tool writes another Home's assets, and an agent cannot
+  accept a proposal, review shared Knowledge, or accept a Project result.
+- **People decide in the browser.** Acceptance and review routes require DSH's own web login
+  (the cookie DSH issues from the URL it prints), or a Bearer token from a private file that
+  scripts can use. Every BizAgent route also checks that the request comes from the loopback
+  address and the same origin, which blocks other websites and DNS rebinding.
+- **The BizAgent API needs the DSH login too.** Other local programs cannot list or change Homes
+  through it without the login cookie.
+- **Other Homes' text is fenced.** Messages, proposals, and Frame content from other Homes reach
+  the model marked as untrusted data, not instructions.
+- **Work and wake-ups start only between Homes with the same owner.** Work for someone else's Home
+  waits until that Home picks it up itself.
+
+What it does not do:
+
+- **Agents can reach the files.** A Home's folder is also its working directory, and DSH agents
+  have shell and file tools. An agent can read or edit its own Home files directly, read other
+  folders your user can read, and could find a token file. BizAgent's rules rely on the agent
+  using BizAgent's tools. Ownership is checked against `directory.yaml`, and `bizagent doctor`
+  reports Home files that no longer load or no longer match their recorded owner.
+- **No multiple users.** Everyone signed in to DSH acts as the owner. Hosts that need accounts
+  should mount the routes from `@bizagent/dsh/host` behind their own login.
+- **No sandbox.** Use DSH's permission modes and sandbox settings to limit what agents may do on
+  your machine.
+
+## Compatibility
+
+`@bizagent/dsh` declares its DSH packages as peer dependencies at `^0.2.1-rc.2`; its development
+dependencies, installation guide, and runtime CI pin `0.2.1-rc.2`, also used for manual Web
+acceptance. See [Verification](verification.md). DSH validates activation compatibility at startup.
+BizAgent records
+`schemaVersion` on every stored record and refuses records it does not understand rather than
+guessing.
+
+## Source map
+
+| File | Responsibility |
+| --- | --- |
+| [index.ts](../src/index.ts) | Plugin entry: wiring, DSH event hooks, system prompt section |
+| [service.ts](../src/service.ts) | BizAgent operations behind the tools and routes |
+| [home-store.ts](../src/home-store.ts) | Home folders, organizations, assets, doctor checks |
+| [ledger.ts](../src/ledger.ts), [work-ledger.ts](../src/work-ledger.ts), [project-ledger.ts](../src/project-ledger.ts), [worklog-ledger.ts](../src/worklog-ledger.ts) | Records in DSH storage |
+| [tools.ts](../src/tools.ts) | Agent tool definitions |
+| [agent-preset.ts](../src/agent-preset.ts) | Sessions BizAgent starts join a preset and get a model |
+| [work-runner.ts](../src/work-runner.ts), [inbox-wake-runner.ts](../src/inbox-wake-runner.ts), [learning-session-runner.ts](../src/learning-session-runner.ts) | Sessions started for Work, mail, and learning reviews |
+| [ui-host.ts](../src/ui-host.ts), [local-human-host.ts](../src/local-human-host.ts) | HTTP routes for the panel and local reviews |
+| [route-guard.ts](../src/route-guard.ts) | Loopback, origin, and DSH login checks for every route |
+| [client/](../src/client/) | Browser panel |
+| [session-surface.ts](../src/session-surface.ts) | Session catalog, current Work and Project summaries, durable tool-result receipts |
+| [frame-admission.ts](../src/frame-admission.ts) | Selected Home snapshots at the DSH step admission boundary |

package/docs/concepts.md

@@ -0,0 +1,192 @@
+# Concepts
+
+DSH runs sessions: one conversation with one model, tools, and a working directory. BizAgent adds
+what lasts across sessions: who an agent is, what it has learned, and the work it shares with other
+agents. This page explains each piece and where you see it in the DSH web app.
+
+Start with the [quick start](quickstart.md) if you have not used the product yet.
+Use the [documentation map](README.md) for configuration and developer references.
+
+## Homes
+
+A **Home** is one long-running agent's identity and memory. It is a folder:
+
+```text
+homes/personal--data-analyst-b3a9d31a/
+  home.yaml          address, display name, owner, revision
+  identity.md        who this agent is and what it is responsible for
+  memory/ insight/ knowledge/ method/   one Markdown file per learned asset
+  orders.csv         files the agent works on (the folder is its working directory)
+```
+
+Every Home has an **address** of the form `type:id`:
+
+| Type | Use |
+| --- | --- |
+| `personal` | One member of the team: a person's own agent |
+| `role` | A role several members can fill, such as Analytics |
+| `capability` | A reusable skill or body of knowledge shared across roles |
+| `business` | The organization's own Home: shared goals and decisions |
+| `line` | The organization's product line, which coordinates its Projects |
+
+Each Home has an **owner**, the person allowed to change it from outside: accept proposals into
+it, accept the Projects it leads, and let other Homes start work in it. In the local setup you own
+every Home BizAgent creates.
+
+An **organization** is a set of Homes created together in their own folder,
+`~/BizAgent/orgs/<organization-id>/`. That folder is also a DSH workspace: BizAgent adds it to the
+top of the sidebar, named after the organization.
+
+Your **personal Home**, `personal:default`, lives next to organizations in `~/BizAgent`, not inside
+one. It is there whether or not an organization exists, and organization agents cannot read it.
+An organization's members can also have `personal:` addresses. Home type and storage scope are
+different: Learning groups your outside personal Home separately from organization Homes.
+
+## Sessions and Homes
+
+Each DSH session is bound to exactly one Home, once, when it starts. The binding follows the
+session's working directory:
+
+1. In a Home's folder (or a folder mapped with `workspaceHomes`): that Home.
+2. Anywhere else in the organization folder: the organization's business Home.
+3. Anywhere else, such as your own code repositories: your personal Home. Work outside the
+   organization never lands in the organization's memory.
+
+**Chat** on a Home in the BizAgent panel opens that Home's long-term chat, its *Principal*.
+
+From your personal Home you can still use the organization: open a read-only Frame on one of its
+shared Homes, propose a lesson to it (the organization reviews it), or hand it a task by mail,
+formal Work, or a Project you lead.
+
+At the start of a session the agent receives:
+
+- BizAgent's working rules, as part of the system prompt;
+- a **Home snapshot**: the identity and a short index of active assets (descriptions only; the
+  agent reads full bodies on demand);
+- a digest of unhandled Inbox messages, if any.
+
+## What a Home learns
+
+The agent saves learning with `bizagent_memory_remember`. Each saved item is an **asset** of one
+kind:
+
+| Kind | Holds |
+| --- | --- |
+| `memory` | An observation in its context ("the March export had duplicate rows") |
+| `insight` | An inference supported by observations |
+| `knowledge` | An established fact or rule ("GMV excludes cancelled and refunded orders") |
+| `method` | A repeatable procedure |
+
+Every asset records its **evidence**: references to the session events it came from, which the
+agent (and you) can read back. An asset has a status:
+
+- `active`: in the Home's index; future sessions see it.
+- `candidate`: saved but not yet trusted. The agent uses candidates when it still needs to check
+  something, then publishes the exact revision it reviewed.
+- `superseded`, `retired`: kept for history, no longer used.
+
+Edits create new revisions and refuse to overwrite a revision someone else changed in the
+meantime.
+
+When a later task uses an asset, the agent records whether it was **confirmed**, **contradicted**,
+or **failed**. These receipts are the asset's track record (its *fitness*) and flag assets that
+need review.
+
+### Corrections stick
+
+When you explicitly correct an agent ("that's wrong, retention cohorts use first-active date"),
+BizAgent notices at the end of the turn and asks the agent, once, to decide whether the
+correction is worth keeping. Ordinary turns cost no extra model call.
+
+### Looking back
+
+- **Worklogs** are short, searchable summaries tied to a session: BizAgent writes one for turns
+  that used tools, and agents write their own for results worth finding later. A Worklog can keep
+  exact copies of the files it mentions.
+- **Learning reviews** let an agent go through earlier sessions and Worklogs it has not reviewed
+  yet, decide what (if anything) to keep, and record that each item was reviewed. A host can run
+  these reviews on a schedule in a separate session.
+
+You see all of this under **Learning**: the memory strata, Worklogs, and the asset ledger with
+each asset's revisions, evidence, and receipts.
+
+## Sharing between Homes
+
+A session writes only to its own Home. Other Homes are reached in three governed ways:
+
+- **Frames.** An agent can open a read-only Frame on another shared Home (not a personal one) to
+  search and read its active assets for the current conversation. Typing `@` in the DSH composer
+  offers shared Homes to select. A selected reference is loaded before the model request and its
+  state appears in the Frame bar. A Frame does not launch another agent or change the author Home.
+- **Proposals.** An agent proposes a new or revised asset to another Home, with its evidence. The
+  target Home's owner accepts or rejects it under **Learning → (Home) → Proposal inbox**. An
+  accepted proposal becomes a new revision of the target Home.
+- **Shared Knowledge.** For rules that belong to a whole product line or platform, agents propose
+  documents to a shared Knowledge store that every Home can search. The line Home's owner reviews
+  them in the BizAgent panel.
+
+## Working together
+
+### Inbox
+
+Homes send each other **Inbox messages**: to and cc recipients, an optional deadline, normal or
+urgent priority. The recipient handles a message from its own session; replies go back to the
+session that asked when it is still around. Messages do not create obligations: a reply or a
+"handled" mark is not completed work.
+
+When the recipient Home has the same owner, BizAgent can start a session in it to read new mail.
+Each Home's `inbox.json` sets when: `immediate`, `batch` (every 15 minutes, the default),
+`scheduled` (a cron expression), or `carried` (only shown at the start of its next session).
+Urgent messages always start one. Unanswered messages are nudged once. A conversation that reaches
+6 hops or 12 messages has to be closed with a conclusion message.
+
+People have an Inbox too: messages to `user:<id>` appear under **My Inbox**.
+
+### Formal Work
+
+When another Home must own a deliverable, an agent dispatches **formal Work**: a goal, acceptance
+criteria, and an idempotency key. If both Homes have the same owner, BizAgent starts a worker
+session in the assignee Home right away. The worker accepts the Work in that session and completes
+it with one result, optionally freezing files from its `artifacts/` folder so the requester reads
+exactly the delivered bytes. The result returns to the session that dispatched the Work. The
+requester can cancel Work until a result is reserved.
+
+Work statuses: `open` → `accepted` → `completing` → `completed`, or `cancelled`.
+
+### Projects
+
+A **Project** is a longer goal with a written "done when" standard. Its lead Home creates it; the
+Project gets its own chat (the *Project Main*), separate from the lead's Principal.
+
+1. The lead may invite shared Homes, such as roles and capabilities, as **Seats**, each with a
+   responsibility. Personal Homes cannot hold Seats; they take part through Work.
+2. It dispatches formal Work with the Project id to any Home; each assignee works in its own Home.
+3. When the linked Work is finished, it **submits** a result claim, with frozen files or a
+   delivered Work result as evidence.
+4. A person accepts the claim under **Projects**, or the lead or the person sends it back for
+   rework. An agent can never accept a Project result.
+
+Project statuses: `open` → `awaiting_acceptance` → `accepted`.
+
+## Find the outcome
+
+| Question | Where to look |
+| --- | --- |
+| Did the lesson save? | Session Home button → Learning; expand the body, evidence, and status |
+| Did another Home take the task? | Work & learning → Work card → View worker Session |
+| What did it deliver? | Expand the Work result; inspect the submitted Project files |
+| Where can I accept it? | Project link → claim and review reason → Accept result; or Projects → My review queue |
+| Where did the agent leave me a message? | My Inbox; reply there to return to the original session |
+
+Agent runtime (`running`, `idle`, `unloaded`), Work delivery status, and Project acceptance are
+separate facts. A worker can be idle after delivery while its Project still awaits human review.
+The Work view is specific to the current session; Projects are scoped to the Home's participation.
+Use the lead/project session or your review queue when a Project is not visible from a worker.
+Turn receipts describe what was recorded then; read the current card/detail for its latest status.
+
+## You, the owner
+
+BizAgent treats the person signed in to the DSH web app as the local owner. That person reviews
+proposals, accepts Project results, and reads **My Inbox**. Agents cannot do any of these, even for
+Homes they belong to. See [Architecture](architecture.md#trust-model) for what this protects
+against and what it does not.