feat: make research resumable across agents

CHANGELOG.md

@@ -4,8 +4,51 @@ All notable changes to DotAIOS will be documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Follow an exact context or selected-project Markdown source from a brief or
+  search excerpt through `search --follow` or the existing read-only MCP search
+  tool. Bounded literal pages retain source version and byte coverage, refuse
+  changed sources, and recheck memory scope on every request.
+- Retain public HTML/text originals and readable research sources with
+  `ingest --workdir`, with qualified destinations and bounded fetching.
+- Discover and resume research with `plan start/checkpoint/inspect --workdir`.
+  The work folder preserves progress, verifies source/result versions and
+  refuses stale updates without writing personal AIOS memory.
+
+### Changed
+
+- The compact brief renders readable `> Source: <path> (excerpt; sha256:...)`
+  provenance only. Follow references move beside the projection as
+  `contextSources` in compact CLI and hook JSON, so the fixed visible budget is
+  not spent on opaque locators. Search text output still prints its `> Follow:`
+  value, and the MCP working-context result is unchanged.
+- Implicit project resolution from the current directory now requires the
+  registered project to be `status: active`, alongside its existing verified
+  mapping and root-identity checks. **Upgrade impact:** a project whose README
+  frontmatter is `status: paused` (or any non-active status) stops identifying
+  implicitly from its own folder; select it explicitly by id or slug, or set it
+  back to `active`.
+- `search <query> --json` is now rejected as an unsupported combination instead
+  of being silently ignored. Use the follow mode or plain query output.
+
+### Removed
+
+- The bundled `research` skill no longer writes its report to
+  `vault/research/deep/<date>-<slug>.md`. Results are retained in the authorized
+  work folder under `research/results/`; when no work folder is available the
+  skill offers a destination instead of saving automatically. **Existing files in
+  `vault/research/deep/` are left untouched** and remain searchable.
+
 ### Fixed
 
+- Project identification reports `Memory: Shared` only inside a validated AIOS
+  folder outside its managed workspace shelf. A unique active verified project
+  still wins; malformed roots plus unsafe, conflicting, or unverified mappings
+  stay closed, and the two-field JSON response remains compatible.
+- Generated global bridges bind AIOS CLI calls to their configured AIOS folder,
+  while portable project bridges reuse that host-managed path suffix without
+  publishing a machine-local path.
 - Managed upgrades recognize exact generated schedule commands from every
   supported predecessor release instead of refusing legitimate installs newer
   than 2.0.11.

CONTEXT.md

@@ -49,17 +49,25 @@ The canonical, deterministic, hard-bounded projection of user memory offered to
 _Avoid_: memory dump, session memory, digest
 
 **On-demand retrieval**:
-A query-shaped, bounded view used to expand beyond working context for a specific task. Its results remain evidence pointers to canonical files rather than new durable truth.
+A query- or source-directed, bounded view used to expand beyond working context for a specific task. Its results remain evidence pointers to canonical files rather than new durable truth.
 _Avoid_: startup context, automatic memory, answer generation
 
 **Source evidence**:
 A retrieved excerpt together with enough provenance to identify its canonical origin and scope. Agent prose without a source reference is not source evidence.
 _Avoid_: generated answer, remembered fact
 
+**Source reference**:
+A derived locator for an observed source version and a continuation position. It grants no access: every follow request rechecks the current memory scope, source membership, and source identity before returning literal text.
+_Avoid_: permission token, permanent link, memory authority
+
 **Memory promotion**:
 An explicit, previewed transition from source evidence into durable user memory. Promotion preserves the source relationship and never treats a session inference as approved truth by default.
 _Avoid_: auto-memory, extraction, summarization
 
+**Research work plan**:
+The work folder's current research goal, limits, completed work, source/result references and next action. Its owned section is updated under a revision; it is a task artifact, not personal memory or an execution runtime.
+_Avoid_: Work Plane, autonomous memory, scheduler
+
 **Host receipt**:
 Reproducible evidence that a supported agent host discovered, invoked, and produced the expected DotAIOS result. Installed or configured state alone is not a host receipt.
 _Avoid_: configuration check, file presence

docs/architecture.md

@@ -93,13 +93,43 @@ budget. When the budget is reached, lower-priority items are omitted and the
 rendered projection says so. Compact CLI output, session-start hook JSON, and
 MCP wrap that unchanged projection in a read-only operational envelope.
 
+An explicit project selection also returns versioned, source-specific
+`coverage` metadata (`contextCoverage` in hook JSON). Version `1` contains
+`selectedProjectReadme: { excerptClipped, budgetOmitted }` and a fixed `notice`
+(null when neither flag is set). `excerptClipped` records shortening at the
+1,200 UTF-16-unit README excerpt limit, after removing the initial title and
+outer whitespace; clipping preserves Unicode surrogate pairs. `budgetOmitted`
+means some or all of the selected project block is absent from the final
+rendered projection, including clipping caused by the budget marker. These
+flags describe only that source and transformation, not coverage of all AIOS
+context. Coverage is absent without an explicit project selection and in Off
+mode; absence is not a completeness claim.
+
+The same coverage notice appears in compact text and hook context, and inside
+MCP's `coverage`. It warns that unavailable text may contain constraints and
+must not be inferred. Coverage has a separate fixed 512-character allowance,
+counting pretty JSON with the longest consumer key and the repeated text notice
+plus separator together. It does not consume the visible projection budget or
+the existing 1,024-character operational allowance. `budget.truncated` still
+reports visible-budget loss only; MCP `complete: true` still means retrieval
+completed successfully. Neither promises the entire README was included.
+
 Within a project-scoped projection, a timeline row is global only when both
 `project` and `project_id` are absent or null. Every present attribution field
 must agree with the selected catalog identity. A unique slug, project alias, or
 stable id may stand alone; an alias shared by multiple catalog records requires
 the matching unique `project_id`. Malformed, conflicting, or differently
 attributed rows are excluded rather than widened into global context.
 
+For This project, catalog discovery reads bounded README frontmatter before
+opening the selected project's body. Sibling bodies stay unread; their size
+does not spend the selected-file limit or prevent a valid brief. Catalog
+identity checks still include slug, project alias, and stable-ID collisions.
+Frontmatter is capped at 16 KiB per record, and an opening delimiter without a
+closing delimiter inside that bound fails closed. Catalog files and directories
+are revalidated around the selected body read so identity changes cannot reuse
+the earlier selection. Shared projection selection is unchanged.
+
 Projection work is bounded separately from visible output. One projection may
 open at most 512 source files and reserve at most 16 MiB of raw source bytes.
 Ordinary context, daily, project README, and signal files are capped at 1 MiB
@@ -140,6 +170,53 @@ a bounded `operational.migration` sibling;
 selection, and `resolve_skill` routes
 workflow intent. There are no compatibility aliases.
 
+### Following a source
+
+Supported context and selected-project Markdown excerpts carry a source version
+and opaque follow reference derived from the same accepted read as the excerpt.
+`source-reference.mjs` owns this observation format; `source-evidence.mjs` owns
+the bounded follow read. The existing CLI `search --follow` and MCP `search_aios`
+follow mode call that operation without introducing another tool or store.
+Working context renders each excerpt with a readable `> Source:` provenance line
+inside its visible budget, and publishes the matching follow reference beside the
+projection as `contextSources` in compact CLI/hook JSON. Only sections that
+survived the budget are listed, so text and reference stay atomic without
+spending the visible budget on a locator. The MCP working-context result is
+unchanged: its non-memory metadata keeps its fixed 1,024-character bound, and an
+MCP caller reaches a follow reference through `search_aios` query results. Query
+ranking is unchanged.
+
+A reference is a locator, not an access grant. Each read rechecks the requested
+memory scope, canonical project identity when applicable, contained source
+membership, root identity, file generation, and content hash. Off returns before
+any filesystem access. A changed or replaced source refuses with no text and
+requires fresh discovery. Unrelated edits between requests do not stale the
+reference. The existing in-request filesystem checks and their race limitations
+still apply.
+
+Follow pages report literal UTF-8 byte ranges, with an advancing `next` reference
+or `null`. The entire serialized JSON response fits the caller's character
+budget. Context headers and portable project READMEs retain a 1 MiB ceiling;
+other eligible context/project Markdown retains a 4 MiB ceiling. Each page
+rereads and validates the bounded source; there is no cache. Unsupported source
+families have no follow reference. See [the source follow contract](source-follow.md)
+for caller examples, coverage semantics, and explicit limits.
+
+### Research progress in a work folder
+
+The explicit `plan --workdir` mode owns one section of the work folder's current
+`plan.md`. It records the agreed goal and limits, completed steps, source/result
+versions and next action. `work-plan.mjs` owns validation, locking, atomic
+publication and local evidence verification. The CLI is an adapter; this path
+does not read or write ambient AIOS or trigger its sync hook.
+
+Work-folder ingestion qualifies public text URLs in the CLI adapter, retains
+originals and readable derivatives, and returns references for the plan. The
+host agent researches and authors the result using its available tools. The
+bundled research skill connects these commands without adding an execution
+runtime. See [research continuation](research-continuation.md) for the caller
+contract and limits.
+
 ### On-demand search
 
 Markdown search is a request-scoped safe corpus transaction. The evidence

docs/research-continuation.md

@@ -0,0 +1,72 @@
+# Research that another agent can continue
+
+An authorized agent can retain research in an ordinary work folder, write a
+cited result, and leave its progress ready for another agent. The bundled
+`research` skill starts by inspecting the current work; the owner does not need
+to know a checkpoint name or supply the previous conversation.
+
+The host supplies search, browsing and execution tools. DotAIOS preserves and
+checks the files those tools produce. It does not launch a background worker or
+establish that an external action succeeded. [Exact source follow](source-follow.md)
+lets an agent expand a clipped memory excerpt before applying its constraints.
+
+## Work-folder commands
+
+Use the admitted CLI executable and argument prefix with these arguments:
+
+```text
+plan inspect --workdir <folder> --json
+plan start --workdir <folder> --input research/inputs/start.json --json
+ingest https://commonmark.org/ --workdir <folder> --json
+plan checkpoint --workdir <folder> --input research/inputs/progress.json --expected <revision> --json
+```
+
+`start` takes `{goal, limits: [], nextAction}`. `checkpoint` accepts completed
+steps, source paths and origins, output paths and their source dependencies,
+unresolved items, status and next action. `plan --help` lists the exact fields.
+Input JSON must already be inside the work folder and is limited to 64 KiB.
+
+`ingest` returns both `original` and `source` file references with byte counts
+and SHA-256 digests. Register both paths, using `source.origin`, then bind an
+authored result to the originals and readable copies it used. Source files live
+under `research/sources/`; authored results live under `research/results/`.
+Repeated identical captures preserve existing bytes. Edited retained files are
+refused rather than overwritten.
+
+The current entry occupies one marked JSON section of root `plan.md`.
+Surrounding user prose remains intact. Completed steps append, and writes require
+the last observed revision. Cooperating writers use a lock and publish the whole
+plan atomically. After an interruption or uncertain save, inspect before retrying;
+an abandoned staging file is never the current plan.
+
+## What verification means
+
+Inspection returns the goal, limits, progress and next action plus a verification
+state. Changed or missing sources/results and stale output dependencies produce
+`needs-attention`. Completion requires a result, current local evidence and no
+unresolved items. An agent must still assess whether the result satisfies the
+goal: hashes establish file continuity, not factual correctness or remote effects.
+
+One folder holds one current research plan. A different goal must be reconciled
+with the owner before replacing the agreed destination. This first workflow is
+bounded to 32 source files, 32 outputs and 64 completed steps; each referenced
+file is at most 16 MiB. It is not a general task database.
+
+## Scope and source limits
+
+Explicit `--workdir` mode is independent of AIOS `--path` mode. It does not read,
+write or sync ambient personal memory; mixed scope flags are refused. Saving
+research into durable personal memory still needs explicit user authorization.
+
+Work-folder URL ingestion accepts public HTTP(S), HTML/XHTML or plain UTF-8 text.
+It rejects credentials, private/reserved destinations, compressed responses and
+unsupported content. DNS answers and every redirect are checked, and each socket
+uses a validated address. Fetching allows five redirects, at most 2 MiB and a
+10-second default deadline spanning DNS through body delivery. `--timeout` can
+set at most 120 seconds. A dry run checks URL syntax and literal destinations;
+it makes no DNS or HTTP request and reports `network: not_checked`.
+
+Extraction can omit material on dynamic or unusual pages. Inspect the retained
+original when a claim needs it; a successful capture does not prove completeness.
+Existing vault ingestion and the older AIOS plan mode retain their own behavior.
+This change does not qualify every existing adapter or certify every agent host.