GEWU_agent/README.md

# GEWU local research-agent pack

Version 0.20.21. Clarifies that local-file ingestion requires the GEWU service MCP and a separate local `gewu-connector` stdio server. Documents connector setup and requires the agent to stop with a setup blocker when the connector or selected file is unavailable, without streaming file bytes as base64 or inventing an upload script. Adds claim-bound online verification observations with URL provenance and explicit limits; web pages are not uploaded or treated as archived evidence. Adds exact answer-basis references for citation-free governing-rule answers while retaining source-citation checks. Requires an explicit operator identity handoff before source transfer and bounds resumed work by learning unit. Fixes Windows updater path handling. Adds safe pack update scripts for Windows and POSIX workspaces. Clarifies Antigravity's MCP argument envelope and required project/budget fields, enforces the one-pass diagnostics/context/run sequence, and distinguishes staged sources from registered sources. It keeps prepared proposal JSON byte-for-byte intact, records safe recovery from one missing outer brace in a copied proposal, distinguishes malformed proposals from valid policy holds, makes clear that run state is created through GEWU MCP rather than local run files, avoids headless shell/cache lookups and run-ID reuse across pack changes, groups proposals by semantic learning, guards against placeholder probes, uses server-side canonical digest preparation, stores compact run pins, makes shared scope opt-in, checks duplicates, bounds citation reads and checkpoints per-source budgets. It clarifies that the service's 50,000 `budget_tokens` cap measures serialized response codepoints rather than model context tokens and recommends separate runs for independently resumable sources.

This pack contains the [agent profile](AGENTS.md), Claude harness pointer ([CLAUDE.md](CLAUDE.md)), shared protocols, four skills and separate pipeline procedures. An existing local host supplies the model and tools. There is no standalone agent engine here.

The pack is source material for a dedicated research workspace or for integration into an existing user project. Install it under `.agents/gewu` with the included reversible installer. It adds marked research-only routing blocks to the root `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`, preserving surrounding user content. Host MCP configuration remains a separate step because it requires the operator's service URL and credential.

| Entry point | Use |
| --- | --- |
| [AGENTS.md](AGENTS.md) | Canonical research agent profile and routing rules. |
| [Online verification](protocols/ONLINE_VERIFICATION.md) | Optional claim evidence excerpts, relation/context and links; pages are not uploaded. |
| [CLAUDE.md](CLAUDE.md) | Harness pointer and configuration for Claude Code and Claude Desktop. |
| [kb-ingest](skills/kb-ingest/SKILL.md) | Turn selected material into evidence-bound proposals. |
| [kb-query](skills/kb-query/SKILL.md) | Retrieve and explain accepted knowledge with citations. |
| [kb-curate](skills/kb-curate/SKILL.md) | Audit a scoped collection and propose corrections/relations. |
| [kb-synthesize](skills/kb-synthesize/SKILL.md) | Build grounded comparisons and syntheses with revision-bound dependencies. |

## Claude support

The pack supports Claude through the [CLAUDE.md](CLAUDE.md) harness pointer. When using Claude (such as Claude Code CLI or Claude Desktop):

1. **Instruction discovery:** Use the marked root routing block to load the canonical profile in `.agents/gewu/AGENTS.md`, its shared protocols, and applicable `kb-*` skills.
2. **MCP integration:** Configure the host's project MCP entry for the authenticated Streamable HTTP endpoint, normally `<service-url>/mcp`. Native host setup is not yet qualified.
3. **Execution model:** Use MCP discovery for the current tool list and argument schemas, then call declared operations such as `search`, `source_capture_url`, `source_capture_text`, `proposal_prepare`, `proposal_evaluate`, `proposal_submit` and `proposal_status`. Consult the pinned contract only to diagnose a concrete missing-tool or schema mismatch. There are no generic `query` or `propose` tools.

## Setting up a project directory

GEWU can be deployed in two configurations: a **dedicated research workspace** or an **existing project directory**.

### Directory layout

```text
<project-root>/
  AGENTS.md                 # Project rules with a marked GEWU research route
  CLAUDE.md                 # Claude rules with a marked GEWU research route
  GEMINI.md                 # Gemini context with a marked GEWU research route
  .agents/
    gewu/                   # Isolated GEWU pack
      AGENTS.md             # Canonical GEWU research agent profile
      manifest.json         # Pack and module registry with checksums
      protocols/            # Shared evidence, scope, and contribution protocols
      skills/               # Modular skill definitions
      kb-ingest/
      kb-query/
      kb-curate/
      kb-synthesize/
      <other-skills>/       # Coexisting user skills (e.g., linter, git)
    pipelines/              # Stage procedures (ingest, query, curate, synthesize)
  Inbox/                    # Explicitly placed source documents for ingestion
  Drafts/                   # Local working notes and unaccepted drafts
  Runs/                     # Resumption checkpoints and local run receipts
```

### Setup steps for a new project directory

1. **Create working folders:**
   Create the project directory along with the standard operational folders:
   ```bash
   mkdir -p my-project/.agents Inbox Drafts Runs
   ```

2. **Install the GEWU agent pack:**
   Run the installer from the pack repository. It copies the pack into `.agents/gewu` and adds reversible discovery pointers:
   ```bash
   python path/to/GEWU/agents/gewu/scripts/install.py install my-project --mode integrated
   ```
   Use `--mode dedicated` for a workspace reserved for research. The installer refuses an occupied GEWU destination and will not replace a pre-existing root instruction file.

3. **Configure the service and local-file MCP servers:**
   Local-file ingestion needs two separate MCP server entries. The authenticated Streamable HTTP server at `<service-url>/mcp` provides GEWU workflow tools but cannot read files from the agent's machine. Configure it with the operator-provisioned bearer credential through the host's secure credential mechanism. The `gewu-connector` stdio server must run on the machine that can access the source file and receive the same appropriately scoped `GEWU_TOKEN` through its protected environment.

   Configure the connector with its service URL and explicit file allowlist. Its launch arguments have this shape (the host's MCP config syntax varies):

   ```text
   gewu-connector --url <service-url>/mcp --file <stable-id>=<absolute-local-path>
   ```

   This command is the long-running stdio MCP server process; the host starts it and owns its lifetime. If the package is not installed in the host's Python environment, configure the host to launch the checkout through `uv run --project <path-to-GEWU> gewu-connector ...` instead. The connector must run where the selected file path exists, and its process must receive `GEWU_TOKEN` through the host's protected environment.

   Add one `--file ID=PATH` for each selected source, and supply `GEWU_TOKEN` through the host's protected environment or secret store. Never put the token in the command arguments, prompt, or checked-in config. The connector provides `list_selected_files` and `upload_selected_file`; the agent must use a listed file ID and the authorized project ID. It streams and resumes bytes internally and returns metadata plus a staged source candidate, not the path or bytes. Do not send whole-file base64 through conversational MCP calls or suggest a one-shot upload script. If the host cannot start the connector, stop and report that setup blocker without claiming upload success. See the [local-file contribution protocol](protocols/CONTRIBUTIONS.md#capture-local-files-through-the-connector) for limits and failure behavior.

   `source_capture_text` is only for UTF-8 plain text or Markdown explicitly supplied by the user (up to 1 MB); it archives and extracts that text but does not register the candidate. `source_capture_url` is available only for public hosts the service operator has allowlisted. It supports UTF-8 text, Markdown, HTML and PDF; HTML citations point into visible-text extraction. PDF extraction requires Linux bubblewrap, Poppler and prlimit, and scanned PDFs report `PDF_NO_TEXT`.

   Supply the non-secret authenticated principal ID alongside the project, selected files and turn budget. For example: `principal_id=agent-pilot; project_id=dome-performance; sources=2017bouillot.pdf; budget=one evidence-backed learning unit this turn`. Keep bearer credentials in the connector/host secret mechanism. If the principal ID is missing, the agent must stop before capture instead of searching credential/configuration files.

4. **Verify each stage separately:**
   Check the pack with `python .agents/gewu/scripts/manifest_tool.py verify`, confirm instruction discovery in the selected host, verify authenticated service diagnostics, then exercise the intended workflow. A successful copy does not qualify host discovery, connection, or workflow.

To remove an installation, run `python .agents/gewu/scripts/install.py uninstall my-project` from the installed pack or original source. Removal restores exact pre-install instruction bytes and removes only unchanged pack files. If a managed file has changed since installation, removal stops and preserves all content for manual review.

### Updating an installed project

The installer is for first-time setup and safe removal; do not run `uninstall` followed by `install` to update a workspace. Older installations may not have an installation receipt, so uninstall can refuse while install correctly refuses to overwrite the existing pack.

When the `GEWU_agent` checkout is a sibling of the project directory, update from the project root with:

```powershell
.\GEWU_agent\update_gewu.bat
```

On Linux or macOS:

```bash
./GEWU_agent/update_gewu.sh
```

Both scripts pull the pack with a fast-forward-only Git update, verify its manifest, back up the installed `.agents/gewu` directory under `.agents/gewu-backup-<timestamp>`, synchronize the pack, and verify the installed copy. They leave project-root instruction files in place. Pack-local edits are replaced by the pulled version; the backup preserves the previous copy. The POSIX script requires `rsync`. The optional first argument is the project directory when the checkout is stored elsewhere, for example `./GEWU_agent/update_gewu.sh /path/to/project`.

## Working with existing agents, skills, and folders

In real user projects, developers often already have agent configurations, custom skills, and active development workflows. GEWU is explicitly designed to coexist cleanly without clobbering existing setups:

### 1. Coexistence with existing agent profiles (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`)

- **Do not overwrite root project personas:** If your project already has a root `AGENTS.md` or `CLAUDE.md` governing code conventions, architectural rules, or development personas, keep that root file intact.
- **Reference routing:** Add a concise routing section to your existing `AGENTS.md` or `CLAUDE.md` pointing to GEWU for research tasks:
  ```markdown
  ## Knowledge base and research (GEWU)
  For knowledge base queries, source ingestion, curation, or research synthesis, follow the GEWU profile in `.agents/gewu/AGENTS.md` and use the `kb-*` skills.
  ```
- **Preserved boundaries:** This ensures normal coding and maintenance sessions are not hijacked by research personas, while allowing the model to switch into GEWU research mode whenever research tasks arise.

### 2. Coexistence with existing skills and skill directories

- **Namespace isolation:** All GEWU skills are prefixed with `kb-` (`kb-ingest`, `kb-query`, `kb-curate`, `kb-synthesize`). They live in `.agents/gewu/skills/`, separate from existing project skills.
- **Host-specific skill folders:** The pack keeps skills namespaced under `.agents/gewu/skills/`. Copying them into host-specific skill folders is not performed by this installer and requires separate host qualification.
- **Self-contained contracts:** Each `kb-*` skill declares only its needed protocols and pipeline files. They do not depend on external harness hooks or proprietary runtime extensions.

### 3. Workspace folder and state boundaries

- **No untracked code mutation:** GEWU does not perform blanket safety commits, modify application source trees, or alter git branches directly.
- **`Inbox/`:** Only documents explicitly placed in `Inbox/` (or explicitly targeted by file path) are processed during ingestion.
- **`Drafts/`:** Working notes and intermediate unaccepted summaries stay strictly in `Drafts/`.
- **`Runs/`:** Private execution checkpoints and progress receipts are stored in `Runs/`.
- **Durable acceptance:** All additions to the shared research knowledge base go exclusively through typed MCP proposals and receive cryptographically bound acceptance receipts from the GEWU service.

### 4. Tool and MCP transport isolation

- The installer does not edit host MCP configuration. Add a uniquely named GEWU server through the host's supported project configuration or CLI, preserving the existing server entries. Host-specific MCP setup and authentication are not qualified by the pack installer.

## Manifest and checkpoint integrity

The [manifest](manifest.json) records module hashes, the checkpoint contract, and the verified local service-contract snapshot. The service snapshot is generated from the actual MCP SDK tool inventory and generated v1 record schemas. Native host acceptance is still NOT RUN. If the installed service tool inventory differs from the pinned snapshot, stop before mutation. Local drafts stay under the selected workspace's `Drafts/` and remain unaccepted; no canonical writes or fabricated receipts are permitted.

The manifest's `modules` array is the authoritative descriptor registry for the profile, harness pointers, protocols, skills and pipelines. Each entry identifies its implementation, provided/required instruction contracts, compatible checkpoint contract and exact file hash. Its snapshot digest covers that array using the declared canonical serialization. Recompute hashes and the snapshot after changing a module; any published pack change requires a new pack version. The entry lists above are discovery indexes and must agree with the registry.

For portable Markdown hashing, decode UTF-8, remove an optional BOM and normalize CRLF/CR line endings to LF, then hash the UTF-8 bytes with SHA-256. Preserve every other character and the final newline. This keeps Windows checkout conversion from changing instruction identity; it is not a signature or proof of trusted origin.

Checkpoint contract `gewu.local-checkpoint@0.1.0` requires run identity, explicit project/shared scope, lens/objective, snapshot digest, resolved module contract IDs and file hashes, host/model metadata where available, input/output hashes, stage, included/excluded/skipped coverage, budgets, pending operation identities and last service receipt. Unavailable service fields are explicitly absent; they are never fabricated. The standalone `scripts/run_checkpoint.py` utility creates and updates private atomic checkpoint files, rejects credential/source-body fields, pins the pack modules, and refuses resume after a snapshot mismatch. For example, initialize with `python .agents/gewu/scripts/run_checkpoint.py init --run-id run-2026-01 --objective 'Compare audience response' --projects dome-performance --lens 'Audience behavior'`; send one bounded JSON patch to its `update` command on stdin and use `show` to validate pins before resuming. The service API persists agent-owned run state through `run_create`, revision-checked `run_checkpoint` and `run_status`; the local helper remains a private recovery mirror. Neither supplies a host scheduler. A successor run requires explicit contract compatibility and downstream revalidation.

`required_service_capabilities` lists the catalog capabilities each module uses; `bound-to-pinned-service-v1` means those names exist in the bundled v1 catalog and MCP contract snapshot. `not-required` means that module makes no service calls. These markers do not qualify a native host connection or prove a live pilot workflow. The installer supplies file-based discovery pointers only; native MCP adapters and client workflows remain unqualified.