docs: make Getting Started and CONTRIBUTING accurate and runnable#78
Merged
Conversation
se-jo-ma
force-pushed
the
docs/getting-started-accuracy
branch
from
c97b4e4 to
37b6423
Compare
Followed the developer onboarding guides end to end and fixed every step that was wrong or did not run: - Correct the Python floor to 3.12 (was 3.14); list the real core deps (clipspy, pyyaml, pydantic) instead of "only clipspy". - Document `uv sync --all-extras` for dev setup. A plain `uv sync` left 16 test modules failing at collection (missing fastapi / cryptography / mcp / prometheus_client) and ran 0 tests; with extras the suite is green (1691 passed, 4 skipped, 1695 collected). - Rewrite the Getting Started rule example so it actually compiles and runs: real list-form `when:` schema, a classification hierarchy + function loaded via load_functions() so `below()` is defined, and the printed decision/reason/rule_trace/module_trace replaced with real executed output (the old example printed a trace for a rule that was never defined). - Fix the README Quick Start snippet, which crashed because it never called load_modules(); it now uses Engine.from_rules(). - Update the CONTRIBUTING test count (1695) and Project Structure tree. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01V8oiyn95VpYzZXH2V2PXSa
The getting-started prose changes (Python 3.12 baseline, expanded core deps, classification-hierarchy section) are embedded into the generated llms-full.txt. Regenerated via `make docs-gen` so the docs drift gate passes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01YFbDHuyErPiiWNEGkEa4kG
fathom-ts/package.json was touched by #51 (repository.url https->git+https), tripping the doc-source drift gate. The repo-url format change doesn't affect this page's content; re-verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017pXsj4Q7q1Vn2mtHhakTtJ Signed-off-by: se-jo-ma <mauk.sean@gmail.com>
pypi-publish.yml bumped actions/checkout v6->v7 (dependabot #87), a mechanical CI bump that doesn't affect this page; re-verified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017pXsj4Q7q1Vn2mtHhakTtJ Signed-off-by: se-jo-ma <mauk.sean@gmail.com>
se-jo-ma
force-pushed
the
docs/getting-started-accuracy
branch
from
4c8c670 to
befdf68
Compare
krakennetworks
approved these changes
Jun 24, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Followed the developer onboarding guides (
docs/getting-started.md,CONTRIBUTING.md,README.md) step by step and corrected every instruction that was wrong or did not run.Fixes
requires-python = ">=3.12").clipspy,pyyaml,pydantic(was "the only core dependency is clipspy").uv sync→uv sync --all-extras. A plainuv syncleft 16 test modules failing at collection (missingfastapi/cryptography/mcp/prometheus_client) and ran 0 tests; with the extras the suite is green (1691 passed, 4 skipped, 1695 collected).when:schema, a classification hierarchy + function loaded viaload_functions()sobelow()is defined, and the printeddecision/reason/rule_trace/module_tracereplaced with the real executed output. The old example printed a trace for aclassification::resolve-levelsrule that was never defined.load_modules(); it now usesEngine.from_rules().Verification
uv sync --all-extras && uv run pytest -q→ 1691 passed, 4 skipped.uv run ruff format --check src/ tests/clean;uv run mypy src/clean with--all-extras.Out of scope / note
reasonhits a CLIPS compiler edge case (bind:+ a classification operator on the same slot emits invalid CLIPS). Used a truthful static reason; classification semantics are intact. Fixing the compiler was out of scope.🤖 Generated with Claude Code
https://claude.ai/code/session_01V8oiyn95VpYzZXH2V2PXSa