# Local setup and first use

This guide gets GEWU running on your machine so you can inspect the reader and run the current implementation checks while preparing pilot documents. The local project registry is disposable test data. It does not include pilot sources, accepted knowledge, named owners, or production acceptance policy.

## Requirements

- Python 3.12–3.14
- Node.js and npm (the web workspace has a checked-in `package-lock.json`)
- Git
- `uv` is recommended. The repository wrapper can create a virtual environment and install the Python development dependencies with `python3` and `pip` if `uv` is unavailable.

Run these commands from the repository root.

## Start a disposable local service

Set one data directory for every command in this shell. It holds the local Git knowledge repository, artifact files, identity database, and test registry. The default is `./.data/gewu` and should remain outside source control.

```bash
export GEWU_DATA_ROOT="${GEWU_DATA_ROOT:-./.data/gewu}"
mkdir -p "$GEWU_DATA_ROOT"
```

Install the synthetic project registry once:

```bash
make seed-test-registry
```

It creates `dome-performance` and `interactive-video`, plus a shared scope and test-only automatic-acceptance policies. It refuses to replace an existing registry. Only use `make seed-test-registry ARGS=--replace` if you deliberately want to reset that registry; this does not clear the rest of the data directory.

Start the API in one terminal:

```bash
make dev
```

The first run installs the Python package and development dependencies. The service listens on `http://127.0.0.1:8000`; check `http://127.0.0.1:8000/health` for `{"status":"ok","service":"gewu"}`. Leave this terminal open while using the browser or an MCP client. The local factory keeps persistent state under `GEWU_DATA_ROOT`.

## Connect the read-only browser

In a second terminal, keep the same `GEWU_DATA_ROOT` value and provision a viewer credential limited to one fixture project:

```bash
export GEWU_DATA_ROOT="${GEWU_DATA_ROOT:-./.data/gewu}"
make provision-credential ARGS="--credential-id local-viewer-dome --principal-id local-viewer --role viewer --project dome-performance"
```

The command prints the bearer credential once. Copy it into a local password manager or another secure place; do not put it in repository files, shell history, screenshots, or chat. To create access for the other fixture project, run the command again with a distinct credential ID and `--project interactive-video`.

Install and start the web workspace in another terminal:

```bash
npm --prefix web ci
npm --prefix web run dev -- --host 127.0.0.1
```

Open the local URL printed by Vite, normally `http://127.0.0.1:5173`. Paste the viewer credential into the connection form. The browser exchanges it for an HttpOnly session cookie; the bearer value is not retained in the page after connection. You can search the selected project, inspect sources and citations when knowledge exists, and disconnect to end the session.

The synthetic registry is empty, so an empty search is expected at this point. This is useful for checking service startup, credential scope, session handling, and the UI shell; it is not an end-to-end document-ingestion demo or a pilot result.

## Exercise contribution tools when you are ready

The API exposes its authenticated Streamable HTTP MCP endpoint at `http://127.0.0.1:8000/mcp`. Provision a separate credential for an agent/editor and only the project it should access:

```bash
make provision-credential ARGS="--credential-id local-agent-dome --principal-id local-agent --role agent --role editor --project dome-performance"
```

Supply the printed token to your MCP host through its protected environment or credential store as `GEWU_TOKEN`. The service URL is `http://127.0.0.1:8000/mcp`. Do not reuse the browser viewer credential. The repository's `gewu-connector` is a selected-file upload bridge, not a general MCP client; see [the local agent specification](architecture/LOCAL_AGENT.md) and [agent pack guide](../agents/gewu/README.md) for its constraints and setup. Native discovery and workflows in Claude, Codex, Antigravity, and OpenCode remain unqualified, so treat any host connection as local experimentation.

When testing contribution flows, use documents you have permission to process and preserve the exact source version and page/section locations. The fixture's automatic acceptance policy is deliberately test-only. Do not treat an accepted local record as an approved pilot decision.

## Run implementation checks

Run the Python checks from the repository root:

```bash
make test
make check
make typecheck
make boundaries
```

Run the frontend checks:

```bash
make web-check
```

Browser tests require the Playwright browser dependencies to be installed for this workspace; then run:

```bash
make browser-test
```

These checks use synthetic fixtures and local test services. They do not need your pilot corpus and do not qualify real-source extraction, semantic answer quality, deployment, or cross-platform behavior.

## Prepare the pilot materials

No real materials are needed for the local setup above. Before calling the two-project pilot qualified, the plan still needs:

- A named first administrator, named owner(s) for each project, and a named shared-library owner.
- Representative source documents for both project domains. Keep original files and identify the edition/version and the locations that support likely claims. NotebookLM exports can be supplied as supporting material, clearly identified as AI-synthesized secondary sources rather than primary evidence.
- A labeled evaluation set of 20–30 questions per project, with expected answer points and the source passages that support them. Include questions whose answer is absent or uncertain so unsupported answers can be measured.
- The intended project boundaries and rules for which records may be accepted automatically and which require owner review.

Keep the source files and question labels in a separate preparation folder until you decide what to ingest. Do not place them in the synthetic registry or commit confidential material to this repository. When ready, share the agreed corpus, question labels, and owner names so the pilot setup and evaluation can be configured against real data. The current gate status is tracked in the [implementation plan](IMPLEMENTATION_PLAN.md) and [acceptance ledger](acceptance/ledger.md).

## Reset local test state

Stop the service with Ctrl+C. To start over, stop all GEWU processes and remove only the disposable data root you configured, then repeat setup. For the default path:

```bash
rm -rf .data/gewu
```

This deletes the local registry, credentials, artifacts, workflow history, and canonical knowledge repository. Do not run it against a data root that contains material you want to keep.

## Current limitations

This is a local development service, not a team deployment. Owner-account recovery and first-owner bootstrap are not complete; no real pilot owners are configured. URL capture is disabled unless an operator configures an exact host allowlist. Search uses lexical retrieval by default; optional local embeddings require a separately installed and digest-pinned model. Consult the [operations protocol](development/OPERATIONS_PROTOCOL.md) before considering shared or remote use.

## Accounts and administration

Open `/admin` on the web service, or choose **Administration** in the navigation.
Username/password is the default human sign-in method. For first setup, choose
**Use an existing credential** and connect with your operator admin key. In
**User accounts**, create your username and chosen password with role **Administrator**.
Disconnect, then sign in with that username/password. Passwords require at least
12 characters; usernames use lowercase letters, digits, dots, hyphens and underscores.

If you do not have an operator key, provision one locally using the service's
`GEWU_DATA_ROOT`:

```bash
scripts/python-tool python scripts/provision_credential.py \
  --credential-id operator-admin --principal-id operator --role admin
```

Keep the returned key in a secure credential store. Bearer secrets cannot be retrieved.
After testing your administrator account, you can revoke the old operator key from
that account's admin panel. Retaining an operator key is optional.

In the admin panel, start with **Projects → Create a project**. Enter its name,
purpose and research questions (one per line). The project ID is generated from the
name and can be adjusted before creation; the owner defaults to your signed-in ID.
The initial policy allows source registration and supported research records that
pass validation. Uncheck automatic contributions to require review instead; owner
review authentication must be configured separately. New projects do not include
other projects by default. The project appears immediately in account and agent
access selectors after creation.

Administrators create user accounts and assign their role and project access:

- **Editor**: reads assigned projects and issues contributing agent keys for them.
- **Viewer**: reads assigned projects; cannot issue contributing agent keys.
- **Administrator**: reads all projects and manages accounts and service access.

Each user opens `/agents` (**Agent credentials**) and signs in to create a key for
each agent or device. Name the agent, choose its projects, and save the displayed
secret. Configure that key as the agent host's GEWU MCP bearer credential. Each key
has a distinct principal ID, visible in the list, for attributed proposals and runs.
Users only see and revoke their own keys, and cannot grant access beyond their own
projects. Administrators can inspect and revoke all keys. Revoke confirmation names
the key; revocation invalidates bearer access immediately.

**Change your password** appears after username/password login in `/agents` or
`/admin`. Enter the current password and the new password twice. All browser sessions
for that account are invalidated; sign in again. Independent agent keys stay valid.
Disabling a user from the admin panel invalidates their sessions and all their keys.
You cannot disable your own account from its current session.

**Recent activity** in `/admin` shows the latest 50 account and credential management
actions. It excludes historical CLI actions, runtime logs and agent runs. Account and
key lists are paged. Reloads and navigation restore your existing session automatically
until it expires (eight hours after sign-in), is revoked, or you sign out. Password
changes also end the session. No secrets or CSRF tokens are persisted in browser storage.

Public password login requires HTTPS. The development proxy preserves the public
Host for the API's same-origin check. Repeated failed logins are temporarily blocked
for 15 minutes. Anonymous registration and email-based password recovery are not
included. Knowledge contributions still go through MCP.