docs: add troubleshooting guide and expand DEVELOPMENT.md#32
Merged
Conversation
- docs/troubleshooting.md: new guide covering developer environment issues (Python version, venv activation, Windows temp dirs, ruff, quickstart-verify failures, schema drift, web UI static drift, Playwright setup), CLI/workspace issues (missing config, pricing table, diff confidence, ingest idempotency, policy diagnosis), server issues (auth errors, event not appearing in diff, SecurityStatusBar, doctor audit_seq), and SDK issues (400 on ingest, 409 on promote, retry semantics) - DEVELOPMENT.md: document package extras table (openai, anthropic, telemetry, all) with when-to-use guidance; explain that core does not import any of them - DEVELOPMENT.md: add smoke-test script comparison table (quickstart-verify vs smoke.sh vs ledger_gate.py) and explain what smoke.sh covers and omits - DEVELOPMENT.md: add 'Adding a SQLite migration' section with step-by-step instructions (add apply block, bump LATEST_SCHEMA_MIGRATION_VERSION, doctor assertion, docs update, test commands, and migration constraints) Co-authored-by: Cursor Agent <cursoragent@cursor.com>
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.
Summary
Documentation-only PR covering three knowledge gaps identified by reviewing recently changed subsystems against the existing docs.
Why
The v1.0.3 release hardened several code paths (ingest edge cases, multi-provider diff, confidence tiers, policy accumulation) and the existing docs were updated to match. However, several developer-facing areas had no documentation:
openai,anthropic,telemetry,all) are listed inpyproject.tomlbut never explained to usersscripts/smoke.shexisted with no documentation linking to it or explaining how it differs fromflightdeck-quickstart-verifyandexamples/ci/ledger_gate.pyDEVELOPMENT.mdandoperations-and-policy.mdwith no consolidated referenceChanges
docs/troubleshooting.md(new)doctor audit_seqgapDEVELOPMENT.md(updated)openai,anthropic,telemetry,all— explains what each installs and notes that core does not import them at runtimequickstart-verifyvsscripts/smoke.shvsexamples/ci/ledger_gate.pyscripts/smoke.shinline description (what it covers, what it omits vs quickstart-verify)apply()block, bumpLATEST_SCHEMA_MIGRATION_VERSION, add doctor assertion, update docs table, run targeted tests) + migration constraintsValidation
uv sync --frozen --extra devuv run python -m ruff check src tests— all checks passeduv run python -m pytest— 93 passeduv run python scripts/generate_schemas.pythengit diff --exit-code schemas/— clean (no model changes)uv run flightdeck-quickstart-verify— OKstorage.py,ledger.py,tests/conftest.py,server/routes/actions.py)Web static not rebuilt (no
web/changes).Schema / Storage Impact
Risk
Docs-only. No code changes.
Notes
Codepaths covered:
src/flightdeck/storage.py(migration pattern,LATEST_SCHEMA_MIGRATION_VERSION,FLIGHTDECK_USE_SYSTEM_TEMP),src/flightdeck/ledger.py(confidence labels, policy evaluation),src/flightdeck/server/routes/actions.py(_LOCAL_CLIENT_HOSTS),src/flightdeck/sdk/client.py(retry semantics),pyproject.toml(extras table).