GEWU/docs/GETTING_STARTED.md

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.

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

Install the synthetic project registry once:

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:

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:

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:

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:

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 and agent pack guide 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.

Give the agent the non-secret principal ID used when provisioning its credential (local-agent in the example), its project, selected connector file IDs and a turn budget. Diagnostics intentionally omits the principal ID. Generate a bounded handoff without reading credentials:

python scripts/prepare_ingest_handoff.py --principal-id local-agent \
  --project-id dome-performance --file-id satie-2017 --max-tool-calls 35

The file ID must match the connector configuration. Repeat --file-id for evidence needed from multiple sources in one learning unit; add --resume-run-id <existing-run-id> when resuming. New source registration also requires an explicitly authorized shared-source grant. The helper does not provision credentials, confer grants or call the service.

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:

make test
make check
make typecheck
make boundaries

Run the frontend checks:

make web-check

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

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 and acceptance ledger.

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:

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 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:

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.