GEWU_agent/README.md

# GEWU local research-agent pack

Version 0.16.0. Adds four default research lenses, non-blocking ingest-review flags, project-scoped feedback guidance and optional Jev relevance scoring; native-host installation and pilot workflows remain unverified.

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. |
| [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:** Compare discovered tools and schemas with `contracts/service-v1.json`, then use declared MCP operations such as `search`, `source_capture_url`, `source_capture_text`, `proposal_evaluate`, `proposal_submit` and `proposal_status`. 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 host MCP connections:**
   Configure the selected host's project MCP entry for the service's authenticated Streamable HTTP endpoint, normally `<service-url>/mcp`, using a bearer credential supplied through that host's secure environment or credential mechanism. Do not put a live token in a checked-in project config. The local `gewu-connector` command is a separate, explicit-file upload bridge; it is not the general GEWU service MCP client. It returns a typed source candidate and never returns the selected path or bytes. Omit `source_revision_id` to derive a content-bound local revision with an exact retry checkpoint, or pass the original ID when resuming an existing workflow. `source_capture_text` archives and extracts explicitly supplied UTF-8 text or Markdown up to 1 MB and returns a candidate marked as pasted text; it does not register the source. To enable URL capture, the service operator may set `GEWU_FETCH_ALLOWED_HOSTS` to comma-separated exact public hostnames. The capture tool archives UTF-8 text, Markdown, HTML and PDF. HTML extraction produces visible text, not markup-byte offsets. PDF extraction currently requires Linux bubblewrap, Poppler and prlimit, runs without network access; mixed text/blank pages are partial and image-only PDFs report `PDF_NO_TEXT` as unavailable.

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.

## 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.