docs: add 10-minute quickstart guide with 3 runnable examples#150
docs: add 10-minute quickstart guide with 3 runnable examples#150
Conversation
Create docs/quickstart.md with prerequisites, install, three copy-paste examples (context build, firewall, routing), expected output excerpts, and next-step links. Update README.md with a prominent quickstart section and fix the context pipeline count from seven to eight stages.
There was a problem hiding this comment.
Pull request overview
Adds a dedicated quickstart entry point to help new users install contextweaver and run three end-to-end examples, and updates top-level docs to point to it and keep pipeline wording consistent.
Changes:
- Added
docs/quickstart.mdwith a 10-minute guide and 3 runnable examples (context build, firewall, routing). - Updated
README.mdto link prominently to the quickstart and corrected the pipeline stage count to eight. - Updated
CHANGELOG.mdunder[Unreleased]to note the new guide and README change.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/quickstart.md | New quickstart guide with install steps + runnable examples + next-step links. |
| README.md | Adds “10-Minute Quickstart” section and corrects pipeline stage count wording. |
| CHANGELOG.md | Documents the quickstart addition and README change under Unreleased. |
| ```powershell | ||
| .venv\Scripts\Activate.ps1 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
The Windows PowerShell venv activation command can fail on default Windows setups due to the ExecutionPolicy blocking scripts (common error: “running scripts is disabled on this system”). Consider adding a short note with a safe workaround (e.g., using activate.bat for cmd.exe or setting execution policy for CurrentUser) so the quickstart remains copy-paste runnable on Windows.
| If you see an error like `running scripts is disabled on this system`, either: | |
| - run the activation script from **Command Prompt (cmd.exe)** instead: | |
| ```cmd | |
| .venv\Scripts\activate.bat |
-
or relax the execution policy for your current user in PowerShell (recommended only on machines you control):
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
| - The tool result was large enough to trigger the firewall during context build. | ||
| - `contextweaver` stored the raw result in the artifact store. | ||
| - The prompt kept a compact summary plus an artifact reference instead of the full payload. |
There was a problem hiding this comment.
The “What just happened” bullets imply the firewall only triggers when the tool result is “large enough”, but apply_firewall() currently intercepts all tool_result items during build (it always stores the raw output as an artifact and replaces text with a summary). Please adjust this explanation to match current behavior, or update the demo to use ContextManager.ingest_tool_result(..., firewall_threshold=...) if you specifically want to demonstrate size-threshold triggering.
| - The tool result was large enough to trigger the firewall during context build. | |
| - `contextweaver` stored the raw result in the artifact store. | |
| - The prompt kept a compact summary plus an artifact reference instead of the full payload. | |
| - The tool result was processed by the firewall during context build (all `tool_result` items go through it by default). | |
| - `contextweaver` stored the raw result in the artifact store. | |
| - The prompt kept only a compact summary plus an artifact reference instead of the full payload. |
| ## 10-Minute Quickstart | ||
|
|
||
| For a guided setup with prerequisites, three runnable examples, expected output, | ||
| and next steps, see [docs/quickstart.md](docs/quickstart.md). |
There was a problem hiding this comment.
The relative link [docs/quickstart.md](docs/quickstart.md) will render correctly on GitHub, but it will likely be broken on PyPI because pyproject.toml sets readme = "README.md" and PyPI doesn’t resolve repo-relative links. Consider linking to the full GitHub URL (or a docs site URL) so the “10-Minute Quickstart” section works wherever the README is rendered.
| and next steps, see [docs/quickstart.md](docs/quickstart.md). | |
| and next steps, see [docs/quickstart.md](https://github.com/dgenio/contextweaver/blob/main/docs/quickstart.md). |
Summary
Create a dedicated 10-minute quickstart guide so new users can install contextweaver, run three working examples, and see tangible output with copy-paste commands.
Fixes #76
Changes
docs/quickstart.md(new) — six-section quickstart guide:build_sync()→ prompt + stats)TreeBuilder→Router→ focused shortlist)README.md— added a prominent "10-Minute Quickstart" section linking to the new guide; fixed the context pipeline feature description from "seven-stage" to "eight-stage" (matchingAGENTS.mdand the actual pipeline)CHANGELOG.md— added entries under## [Unreleased]Checklist
make cipasses locally (fmt + lint + type + test + example + demo)makeunavailable on Windows; ran CI-equivalent commands individually:ruff format --check src/ tests/ examples/— 80 files already formattedruff check src/ tests/ examples/— all checks passedmypy src/— no issues in 41 source filespytest -q— 536 passedpython -m contextweaver demo— passedCHANGELOG.mdupdated under## [Unreleased]AGENTS.md,.github/copilot-instructions.md,.claude/CLAUDE.md— no updates needed. The quickstart is user-facing, and the "seven→eight" fix in README aligns it with whatAGENTS.mdalready documents.Notes for reviewers
pack.token_countandpack.budget, which do not exist onContextPack. The quickstart usespack.stats.*fields that actually exist. The issue also linked to future framework integration guides not yet authored — the quickstart links to existing docs instead and notes integrations as planned separately.source .venv/bin/activate(Linux/macOS) and.venv\Scripts\Activate.ps1(Windows PowerShell).