Metadata-Version: 2.4
Name: bundlewalker
Version: 0.5.0
Summary: Build a review-first personal knowledge wiki with OKF and PydanticAI.
Project-URL: Homepage, https://github.com/HendrikReh/BundleWalker
Project-URL: Documentation, https://github.com/HendrikReh/BundleWalker#documentation
Project-URL: Repository, https://github.com/HendrikReh/BundleWalker
Project-URL: Issues, https://github.com/HendrikReh/BundleWalker/issues
Project-URL: Changelog, https://github.com/HendrikReh/BundleWalker/blob/master/CHANGELOG.md
Author: Hendrik Reh
Maintainer: Hendrik Reh
License-Expression: GPL-3.0-or-later AND CC0-1.0
License-File: LICENSE
License-File: LICENSE-SCOPE.md
License-File: LICENSES/CC0-1.0.txt
License-File: THIRD_PARTY_NOTICES.md
Keywords: knowledge-base,markdown,mcp,okf,pydantic-ai
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Documentation
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.15,>=3.13
Requires-Dist: jsonschema<5,>=4.26
Requires-Dist: markdown-it-py>=4.0.0
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: pydantic-ai>=2.10.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: starlette<2,>=1.3.1
Requires-Dist: typer>=0.16.0
Requires-Dist: uvicorn<1,>=0.51
Description-Content-Type: text/markdown

# BundleWalker

[![CI](https://github.com/HendrikReh/BundleWalker/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/HendrikReh/BundleWalker/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/bundlewalker?label=PyPI)](https://pypi.org/project/bundlewalker/)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later%20%2B%20CC0--1.0-blue)](LICENSE-SCOPE.md)

BundleWalker is a local-first tool that turns a source bundle into a navigable knowledge workspace for people and AI agents.
It proposes review-first writes to cited, interlinked OKF Markdown while preserving the exact bytes
of every accepted source as immutable evidence.

[Tutorial](docs/tutorial.md) · [User Guide](docs/user-guide.md) ·
[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) ·
[Security](SECURITY.md) · [Support](SUPPORT.md) · [License](LICENSE-SCOPE.md)

## Why BundleWalker

- **Keep knowledge local.** Sources, indexing, exploration, and compiled knowledge remain ordinary
  files inside a workspace you control.
- **Review every proposed write.** Model output is validated and shown as a complete diff before
  you decide whether it becomes durable knowledge.
- **Trace answers to evidence.** Cited answers link back to the OKF Markdown concepts they read,
  while accepted source bytes stay unchanged.
- **Use the same workspace from different interfaces.** Work directly through the command-line
  interface, connect an AI agent through the local MCP server, or inspect and resolve work in the
  local browser cockpit.
- **Recover safely.** Authenticated transaction state lets an accepted write finish or roll back
  after interruption without silently accepting a partial result.

## Project status

BundleWalker is a public beta for technical solo users; it is not a claim of production stability
or a service-level commitment. The current public beta is `0.5.0`. See the
[Changelog](CHANGELOG.md) for the immutable release history.

macOS and Linux are supported; Windows is experimental.

## Install BundleWalker

BundleWalker requires Python 3.13 or 3.14 and [`uv`](https://docs.astral.sh/uv/).

Install the exact public beta as an isolated command-line tool:

```bash
uv tool install "bundlewalker==0.5.0"
bundlewalker --help
bundlewalker-mcp --help
bundlewalker-web --help
```

Keep the exact version in the install command for reproducible setup. If you want to contribute or
run from a source checkout, use the separate
[development setup](CONTRIBUTING.md#development-setup).

The local web cockpit is included in the standard Python package; there is no separate web
install. The equivalent conventional installation is:

```bash
pip install bundlewalker==0.5.0
bundlewalker-web --help
```

From a current source checkout, `uv sync --locked` installs the same web runtime for development
and testing.

## Create your first workspace

Create one portable Markdown source, initialize a personal workbook, and run the offline health
check:

```bash
printf '%s\n' \
  '# Review-first knowledge' \
  '' \
  'A review gate separates a model proposal from durable knowledge.' \
  'Accepted source bytes remain immutable evidence.' \
  > example-notes.md

bundlewalker init ./my-knowledge --conventions-style personal-workbook
bundlewalker doctor ./my-knowledge
cd ./my-knowledge
```

`doctor` is deterministic, offline, and read-only. Before the first model-backed command, export
`BUNDLEWALKER_MODEL` and the provider credential required by that model. The
[provider setup guide](docs/user-guide.md#model-and-provider-setup) explains model strings,
provider-specific variables, and safe credential handling without making a provider or model
availability claim.

```bash
export BUNDLEWALKER_MODEL='<pydantic-ai-model-string>'
bundlewalker ingest ../example-notes.md
bundlewalker ask 'Why does this workspace use a review gate?'
```

`ingest` validates and displays a complete prospective diff: answer `y` to accept it or `n` to
leave live knowledge unchanged. Plain `ask` is read-only and returns a cited answer without saving
a Synthesis. Continue with the [Tutorial](docs/tutorial.md) for the complete first journey, or see
the [User Guide](docs/user-guide.md#ingest-and-review-a-source) for source rules and review outcomes.

## Choose how to use BundleWalker

### Command-line interface

The installed `bundlewalker` command is the primary interface for creating, checking, ingesting,
querying, reviewing, and protecting a workspace. Start with `bundlewalker --help`; use the
[complete CLI reference](docs/user-guide.md#complete-cli-reference) when you need options, exit
codes, limits, or recovery procedures.

### MCP server

The existing local MCP `stdio` server fixes one workspace at startup and exposes strict resources
and tools for read-only exploration, model-backed preparation, and explicit review decisions:

```text
bundlewalker-mcp --workspace /absolute/path/to/workspace
```

It is local `stdio`, not a hosted, remote, HTTP, or web-server transport. See the
[host-neutral MCP guide](docs/user-guide.md#use-bundlewalker-through-a-local-mcp-host) for its
resource and tool contract. Hermes Agent users can follow the dedicated
[Hermes MCP setup guide](docs/hermes-mcp-setup.md). Visual Studio Code users can follow the
[VS Code/Copilot MCP setup guide](docs/vscode-copilot-mcp-setup.md); the
[MCP compatibility record](docs/mcp-compatibility.md) distinguishes observed host evidence from
documented but untested combinations.

### Local web UI

The explicitly launched local web UI is a review cockpit for one workspace. It can Browse and
search concepts, Ask cited questions, run deterministic or semantic lint, prepare pasted text or
one `.md`/`.txt` file, prepare Syntheses and refreshes, inspect the complete exact diff, and Apply
or Discard the whole proposal.

From a workspace or with an explicit workspace path, run:

```bash
bundlewalker-web
bundlewalker-web --workspace /absolute/path/to/workspace
```

The process binds an operating-system-selected port on `127.0.0.1`, opens a single-use
authenticated URL in the default browser, and stays attached to the terminal. If the browser does
not open, copy the complete URL printed in the terminal without sharing it. Press Ctrl-C to stop
the server and invalidate its in-memory browser sessions.

One process serves one workspace, with the same zero-or-one pending-review state used by the CLI
and MCP server. A proposal prepared through MCP therefore appears in the browser and can be
resolved there by its exact opaque review ID. Host, session, Origin, and CSRF checks protect the
loopback browser boundary; the UI loads only packaged same-origin assets.

The first web release intentionally excludes remote access, multiple workspaces, accounts,
background service operation, workspace initialization, migration, backup, restore, and
configuration editing. macOS and Linux are supported; Windows is experimental. See the
[local web cockpit guide](docs/user-guide.md#use-the-local-web-review-cockpit) for the complete
workflow, security boundary, and troubleshooting.

## Understand reviewed writes

Every reviewed write follows the same boundary:

```text
prepare -> deterministic validation -> complete diff -> explicit decision -> atomic commit
```

- Deterministic operations such as `init` can create known scaffolding without a model or review;
  `doctor`, `workspace status`, and plain `lint` inspect state without changing knowledge.
- Read-only operations such as plain `ask` and semantic lint may use a model, but do not prepare or
  persist knowledge writes.
- Prepare-only MCP operations validate a proposal and store at most one private pending review;
  they do not change live `raw/` or `wiki/` content.
- Applying operations revalidate the exact accepted proposal before committing it. The CLI applies
  only after your affirmative decision; MCP applies only the matching review ID. Declining or
  discarding a review leaves live knowledge unchanged.

Accepted source bytes are copied unchanged into `raw/` under content-derived names and never
rewritten. The compiled OKF Markdown in `wiki/` can evolve through later reviewed writes. Interrupted
accepted writes can complete or roll back safely, while a prepared review remains pending until it
is explicitly applied or discarded. The [review and recovery guide](docs/user-guide.md#maintain-and-recover-the-bundle)
documents duplicate no-ops, stale reviews, crash recovery, and the full decision contract.

## Operate and protect a workspace

Inspect compatibility before copying or changing a workspace, back it up outside itself, restore
only into a separate target, and request format upgrades explicitly:

```text
bundlewalker workspace status [PATH]
bundlewalker workspace backup OUTPUT [--workspace PATH]
bundlewalker workspace restore ARCHIVE TARGET
bundlewalker workspace upgrade [PATH] [--backup-dir DIRECTORY]
```

Backups can contain exact raw source bytes. Read the authoritative
[workspace compatibility and portable-backup policy](docs/workspace-compatibility.md) before a
backup, restore, upgrade, or rollback. The [reviewed performance and capacity evidence](docs/performance-and-capacity.md)
defines the measured support envelope and its exclusions.

Use `bundlewalker doctor [PATH] [--report REPORT.json]` for an offline, read-only diagnostic and an
optional redacted support report. If report creation fails after its target is created, inspect and remove
the owner-only partial target when appropriate before retrying; BundleWalker retains it to avoid deleting
an unrelated replacement installed at the same path.

## Documentation

Each active document has one canonical job:

- This README is the product landing page for maturity, platforms, installation, the shortest
  useful workflow, interface choice, reviewed-write safety, and navigation.
- The [Tutorial](docs/tutorial.md) is the reproducible personal-workbook journey from source notes
  through reviewed knowledge, refresh, health checks, backup, and restore.
- The [User Guide](docs/user-guide.md) is the canonical task, CLI, MCP, lifecycle, recovery, limits,
  and troubleshooting reference.
- The [Hermes MCP Setup Guide](docs/hermes-mcp-setup.md) covers portable Hermes-specific MCP
  registration, tool filtering, environment forwarding, verification, and removal.
- The [VS Code/Copilot MCP Setup Guide](docs/vscode-copilot-mcp-setup.md) covers workspace-scoped
  registration, secret inputs, tool selection, approvals, resources, logs, and removal.
- The [MCP Host Compatibility Record](docs/mcp-compatibility.md) publishes the tested host matrix,
  exact environment, capability evidence, and limits of each certification claim.
- The [Workspace Compatibility Policy](docs/workspace-compatibility.md) defines workspace formats,
  backup, restore, upgrade, rollback, and portability boundaries.
- [Performance and Capacity](docs/performance-and-capacity.md) publishes reviewed evidence, the
  supported-capacity statement, exclusions, profiles, and reproduction procedure.
- The [Release Procedure](docs/maintainers/releases.md) is the maintainer reference for current
  TestPyPI and production-PyPI trusted publishing and immutable release recovery.
- [Contributing](CONTRIBUTING.md) covers architecture, contributor workflow, verification,
  documentation ownership, and the historical-record policy.
- The [Security Policy](SECURITY.md) defines the supported reporting scope and private vulnerability
  route.
- The [Support Policy](SUPPORT.md) defines supported platforms, issue-reporting evidence, and the
  best-effort maintenance boundary.
- [License Scope](LICENSE-SCOPE.md) maps GPL and CC0 paths and explains how user content and generated
  workspaces are treated.
- The [Changelog](CHANGELOG.md) preserves immutable tagged history and the concise Unreleased record.

## Development

The default suite is offline and requires no model credentials:

```bash
uv run pytest -m 'not eval' -q
uv run ruff format --check .
uv run ruff check .
uv run pyright
```

Live model-quality evaluation is explicit, opt-in, may use the network, and may incur provider
cost. See [Contributing](CONTRIBUTING.md) for architecture, setup, test layers, and change workflow.

## License

BundleWalker's application code, tests, documentation, and internal agent prompts are available
under the [GNU General Public License version 3 or later](LICENSE). The five packaged convention
presets are dedicated under [CC0 1.0 Universal](LICENSES/CC0-1.0.txt). User-provided sources and
generated knowledge remain subject to the rights in that content; processing does not make them
BundleWalker-owned. See [License Scope](LICENSE-SCOPE.md) for the exact path mapping.

Copyright (C) 2026 Hendrik Reh
