Retro improvements from the v1.14.0 release:
- release-image-test.sh gains a `probe` scenario (part of `all`) that
runs the two container-level checks done by hand during v1.14.0:
OPEN_NOTEBOOK_WORKER_MAX_TASKS reaching the in-image worker (#1141's
supervisord `sh -c` expansion), and the worker surviving startup with
HTTP_PROXY set while the user's NO_PROXY value is preserved (#1160,
internal SurrealDB websocket not tunneled). Self-contained standalone
containers with their own cleanup, so a probe failure can't leak into
the fresh/upgrade scenarios.
- RELEASE_PROCESS.md documents two gotchas the release hit: never leave
the version bump uncommitted on a branch (it leaked into an unrelated
fix PR), and a post-tag fix requires a full re-cut (move tag + rebuild
images), not just a tag nudge, or publication promotes the un-fixed
artifact to v1-latest.
Verified: `release-image-test.sh probe lfnovo/open_notebook:1.14.0`
passes 4/4.
Retro improvements from the v1.13.0 release:
- rc-stack.sh 'up' now docker-pulls lfnovo/open_notebook:<tag> by default so a
same-named local build can't shadow the registry artifact during Phase 6
verification (non-fatal for local-only tags).
- New --with-runtimes flag enables the opt-in heavy engines (Docling +
Crawl4AI) on the RC stack via RC_ENABLE_DOCLING/RC_ENABLE_CRAWL4AI, so the
published image's opt-in install path can be exercised with real data. The
release-test compose defaults these empty, keeping fresh/upgrade tests fast.
- Documented both gotchas (local-tag shadowing; judging opt-in gating on a
clean image vs a dev venv with runtimes installed out-of-band) in
RELEASE_PROCESS.md.
Docling and local Crawl4AI are now opt-in, installed on first container startup
via OPEN_NOTEBOOK_ENABLE_DOCLING / OPEN_NOTEBOOK_ENABLE_CRAWL4AI, keeping the
default image lean (Crawl4AI un-bundled). Downloads cache on the /app/data
volume; installs are blocking with loud logs and degrade-don't-die on failure.
A GET /api/capabilities probe reports actual availability and the Settings UI
gates the Docling/Crawl4AI engines and OCR toggle (with env-var hints) until the
runtime is present. Docs folded from #1121 and rewritten to opt-in; ADR-007 added.
Closes#1122. Closes#1105.
Captures the process designed and executed for v1.11.0 so every future
release reproduces it:
- .github/RELEASE_PROCESS.md v2: changelog audit, risk-based test
matrix (buckets A/B/C), the Docker image gate, fix-loop re-test
policy, CI-based publishing path, communication structure with a
mandatory credits section, retro, and the gotchas that cost
iterations this cycle
- ADR-005: why releases now pass a risk-based confidence process gated
on the real image, with the v1.11.0 evidence (bugs the unit suite
could not catch: SEARCH-index ORDER BY 500, credential clear no-op)
- scripts/release-test/: the harness built during v1.11.0 —
fresh-install + upgrade gate (release-image-test.sh) and the
browsable RC stack with optional dev-data copy (rc-stack.sh), plus
compose/nginx encoding the API_URL, host.docker.internal and
SurrealDB import learnings
- make release-test / release-stack / release-stack-down targets
* docs: restructure documentation around AGENTS.md, VISION.md and decision records
- Consolidate 17 CLAUDE.md files into 3 AGENTS.md (root, backend, frontend);
CLAUDE.md files become @AGENTS.md pointers
- Add VISION.md: product identity + current posture with horizon clusters
- Add docs/7-DEVELOPMENT/decisions/ with 4 retroactive ADRs and 2 PDRs
- Add 5 new engineering docs pages (credentials, content-processing,
podcasts, prompts, frontend) absorbing knowledge from removed CLAUDE.md
- Dismember TRIAGE.md: label taxonomy into maintainer-guide.md, product
jurisprudence into VISION.md, operator heuristics stay local (gitignored)
- Add AI-assisted/agent-generated PR guidelines to contributing.md
- Convert README.dev.md into a pointer after migrating its unique content
(make workflow matrix, Docker publishing, add-a-language playbook)
- Fix stale docs: migration path/format, provider count, locale list;
fix broken links (docs/index.md, PR template, CONFIGURATION.md)
* docs: fix README doc links and add markdown link check to CI
- Repoint 9 README links to pages that actually exist in docs/
- Replace literal (link) placeholder in maintainer-guide templates
- Add scripts/check_md_links.py validating relative links in tracked
markdown (skips URLs, anchors and code spans)
- Add docs-links workflow running the check on PRs that touch markdown
* docs: add documentation restructure to changelog
* feat: add cubic.yaml with project-aware AI review agents
Three custom review agents (vision & principles alignment backed by
VISION.md, known mechanical caveats, security & testability), PR-contract
review instructions, and automatic ultrareviews for auth, credential,
encryption and migration changes.
* docs: graduate issue-first policy by change size
Small obvious fixes (typos, docs, tiny bugs, i18n completions) no longer
require an issue; features and architecture changes still do. Sizeable
PRs opened without an issue convert to draft while the issue goes
through triage (1-2 days). Applied consistently across contributing
guide, root CONTRIBUTING pointer, PR template, maintainer guide red
flags and cubic review instructions.
* docs: align PR template Related Issue section with graduated issue-first policy
* docs: address review — generalize ADR-002/004, unwrap hard-wrapped lines
- ADR-002 now records the general delegation rule (platform/media support
that needs heavy coding lives in focused external libraries) covering
Esperanto, Content Core and podcast-creator
- ADR-004 now records the durable decision (long-running work runs on
background workers — heavy content, varied machine sizes, never lock
usage) with the queue technology as a swappable implementation detail
pending #381
- Remove mid-paragraph hard line wrapping from authored docs to match
repo convention (one line per paragraph)
* fix: address cubic review — stale doc facts, make dev/full targets, link checker query strings
- credentials.md: only PROVIDER_CONFIG exists as a map; Vertex/Azure/
OpenAI-compatible provisioning is inline in _provision_*() functions
- content-processing.md: correct ContextConfig priority weights
(source 100 > insight 75 > note 50)
- development-setup.md + Makefile: make dev/full pointed at root compose
files that don't exist; targets now use examples/docker-compose-dev.yml
and examples/docker-compose-full-local.yml with --project-directory .
- check_md_links.py: strip query strings before file-existence checks
* Enhance export_docs.py with Table of Contents feature
Added a Table of Contents generation feature to the documentation export script, enhancing navigation through consolidated markdown files.
* fix: remove duplicated orphaned code from export_docs.py
The TOC change accidentally duplicated consolidate_folder/main and left
the old body orphaned after the __main__ guard, causing an IndentationError.
Keep only the intended TOC generation so the script runs again.
---------
Co-authored-by: Luis Novo <lfnovo@gmail.com>
* fix(docker): make wait-for-api.sh POSIX and enforce LF line endings (#586)
* fix: restore inline comment on final exit 0
Addresses review feedback: the comment on the final `exit 0` explains
a non-obvious design decision (frontend still starts when the API
never became ready, so users get a usable UI with connection errors
rather than a dead container).
---------
Co-authored-by: Luis Novo <lfnovo@gmail.com>
Users reported "Unable to Connect to API Server" errors on startup
because the frontend started before the API finished initialization
(database migrations, etc.).
- Add wait-for-api.sh script that polls /health endpoint
- Update supervisord configs to use wait script instead of sleep 5
- Waits up to 5 minutes for API to be ready before starting frontend
- Applies to both single-container and multi-container deployments
Fixes#315
