deployment.md

# Deployment and offline bootstrap

The reusable Skill is `skills/book-assistant/`. Its frontmatter and `agents/openai.yaml` follow the skill-creator workflow; it is compact and routes deployment, package/query rules, public host interfaces, and visual evidence to references.

Runtime **0.1.0** is distributed from this project's reviewed `book-agent/` source. Its Python distribution is `prebuilt-book-agent`; its CLI is `book-agent`. Build output must include a release manifest with version, source location/hash, artifact hashes, and license inventory. The delivered runtime must not contain the example corpus, API keys or unapproved model weights. Optional approved weights ship separately with a file-hash receipt and license inventory. Installing the Skill alone cannot supply a missing runtime.

## Verified local artifacts

`skills/book-assistant/scripts/bootstrap.py` accepts only local approved wheel artifacts. It is a standard-library program, so it works before Book Agent's dependencies are installed. Its release manifest format is:

```json
{
  "version": "0.1.0",
  "source": {"path": "book-agent-reviewed-source.zip", "sha256": "<actual source archive hash>"},
  "artifacts": [
    {"path": "prebuilt_book_agent-0.1.0-py3-none-any.whl", "sha256": "<actual wheel hash>"},
    {"path": "dependency.whl", "sha256": "<actual approved dependency hash>"}
  ],
  "licenses": [{"component": "book-agent", "license": "<declared project license>"}]
}
```

These hashes are generated from actual build artifacts. Obtain the expected **manifest hash** through a trusted delivery channel; the bootstrap does not invent a publisher identity from package checksums. It verifies that hash, the actual local source archive, every approved wheel and wheel metadata, and pins Book Agent's reviewed version. Relative source/wheel paths must remain within the release directory. Wheels are copied into a temporary wheelhouse containing only approved artifacts.

The bootstrap installs with pip's isolated mode, `--no-index`, `--require-hashes`, and that approved wheelhouse. It does not run a remote installation script or silently fetch omitted dependencies. A dependency-complete offline wheelhouse is needed for a clean machine. A missing wheel produces an installation error. Select a new virtual-environment directory, or a prior bootstrap-owned environment; unrelated existing environments are refused.

```powershell
python .\skills\book-assistant\scripts\bootstrap.py --manifest ".\Delivery\release-manifest.json" --manifest-sha256 "<trusted manifest SHA-256>" --venv ".\BookAgentRuntime\venv"
python .\skills\book-assistant\scripts\bootstrap.py --manifest ".\Delivery\release-manifest.json" --manifest-sha256 "<trusted manifest SHA-256>" --venv ".\BookAgentRuntime\venv" --install
& ".\BookAgentRuntime\venv\Scripts\book-agent.exe" --version
```

Without `--install` it prints a validated plan and creates no environment. Successful installation records `.book-agent-bootstrap.json` with artifact provenance and reports the installed distribution version. Installation failure does not imply successful runtime verification.

The bootstrap excludes `offline-wheelhouse/` by default, preserving the lightweight route. Add `--with-local-query` to both planning and installation when offline vectors are wanted; it includes the optional CPU wheels and the application's `local-query` extra. It does not activate vectors or install/copy weights.

This source workflow is compatible with Python on Windows/macOS/Linux. Platform executables are separate build artifacts: claim an executable platform only after that platform's build and checks. Offline bootstrap does not establish that an existing book query encoder, reranker, or the harness's language model operates offline. Those dependencies require their own inspection.

## Import, check and deploy

```powershell
book-agent init "E:\Books\示例书" --reranker none --json
book-agent configure "<registered-book-id>" --vector-search none --json
book-agent doctor "<registered-book-id>" --json
book-agent install-host "<registered-book-id>" --host codex --dry-run --json
book-agent install-host "<registered-book-id>" --host codex --json
```

The default workflow uses existing book text for lightweight lexical/FTS retrieval, original Skill navigation and PDF/EPUB source/image tools. It requires no query-model weights or API key. State, sidecars and deployment artifacts are stored in the configured BookAgentData directory. The original archive/database/Skill is preserved. See [host integration](hosts.md) for configured targets, ownership, backups and manual import steps.

## Optional vector queries

| Route | Configuration | Requirements |
| --- | --- | --- |
| Lightweight default | `--vector-search none` | Existing book package; no model download or query key |
| Offline vectors | `--vector-search offline` | Original compatible local checkpoint and optional Python `local-query` dependencies |
| Online vectors | `--vector-search online` | Inherited reviewed endpoint, explicit authorization and the user's own credential reference |

Register the book with `init`, then select a route with `configure`; registration defaults to `none`. Existing document vectors are reused for either vector route. Query encoders must satisfy the original index's model/revision, normalization, prefix and metric contract; no new document model is selected and no document embeddings are regenerated. When a query model or service is unavailable, diagnostics retain the limitation and permitted lexical fallback remains labeled.

The standard portable onedir binary includes lightweight retrieval and HTTP query support. Local neural query execution is optional through the Python runtime with `local-query` dependencies. The default runtime does not require the large local query framework or its model weights. The main agent model is separate from retrieval and may still be remote.

The separate Windows CPython 3.13 offline wheelhouse can be installed with the delivered `install-offline.py` helper alongside the release manifest (its source location is `packaging/install-offline.py` in the source archive). Use its local artifact/receipt checks and documented options; neither offline query execution nor that local installation needs an API key. This wheelhouse has a platform/Python version scope and does not establish Linux/macOS binary support.

The delivered offline BGE-M3 weight directory uses the original `BAAI/bge-m3` checkpoint. Its portable SHA-256 receipt verifies the files after copying. Keep one weight directory for all books sharing that compatible index contract, then validate it and bind the actual destination path for each book:

```powershell
book-agent install-query-model "<book-id>" --model-dir "<weights-directory>" --json
book-agent configure "<book-id>" --vector-search offline --query-model-path "<weights-directory>" --json
```

`install-query-model` does not download by default or set the book's query path; `configure --query-model-path` binds that path. A separate `--download` request fetches only the inherited original checkpoint into the chosen model directory; it is optional and never a model-selection wizard. A supplied weight directory avoids repeated downloads. Include approved optional dependency wheels when preparing a fully offline Python installation, and review delivered model/dependency licenses before redistribution.

The audited package's SiliconFlow route is optional and uses the user's own account. Select it only when online vectors are wanted; the lightweight route and supplied local weights do not require that service.

No remote endpoint is authorized merely because a manifest names it. If the original query encoder sends questions remotely, disclose that transfer. If the user enables a remote reranker, disclose that it may receive both question and candidate book text. Tool evidence and images may also be passed to the host's remote main model. Keep credential values out of deployment configs and diagnostics.

After applying a host configuration, perform MCP initialization and tool checks independently. Then ask the actual agent an evidence question. If a visual answer is required, inspect actual delivered pixels or explicitly record that interpretation has not been verified. Artifact generation and host config checks are not agent acceptance.