Skip to content

docs: the export-targets and pre-processing epics, read back against the code - #805

Merged
JArmandoAnaya merged 1 commit into
mainfrom
docs/export-targets-and-preprocessing
Aug 26, 2026
Merged

docs: the export-targets and pre-processing epics, read back against the code#805
JArmandoAnaya merged 1 commit into
mainfrom
docs/export-targets-and-preprocessing

Conversation

@JArmandoAnaya

Copy link
Copy Markdown
Contributor

The closing documentation pass for the export-targets epic (#784) and the pre-processing epic (#785). Every page the two epics touched, or should have touched, was read end to end and each claim it makes was checked against the code on main; what follows is what was wrong, per document. No page gains prose for its own sake, and the two generated references (mcp-tools.md, the target table in releases.md) are untouched because their drift gates already pass.

What was wrong, per document

  • README.md - the quickstart still exported with --format yolo; the Export row named no target and no recipe; the monorepo map listed formats/ as yolo, coco, …, had no preprocessing/ line, and counted 38 agent tools and two deletions where the served listing has 56 and four. The Export row now says an export is addressed to the model it will train, and a Pre-process row points at docs/content/preprocessing.md.
  • CHANGELOG.md - neither epic's entry mentioned the browser: the Target model picker and its consent copy, the Pre-processing view and the export dialog's recipe control. The yolo alias moves from a line inside the rename entry to its own Deprecated entry, which is the line the epic's decision A5 asked for.
  • docs/content/tutorial.md - the export step used --format ultralytics; it now introduces visionset target list and exports with --target yolo11, which is the unit every other surface offers.
  • docs/content/api.md - the route list had no preprocessing-recipe routes, no preview route, and no recipe= on the export and compatibility routes.
  • docs/content/mcp.md - the counts were three generations stale: "forty-nine by default plus three" is fifty-six plus four, "twenty-seven added since" is thirty, and the recipe trio and the fourth deletion were missing from the list of what was added.
  • docs/content/preprocessing.md - amount was described as 0 to 0.5; the model refuses zero (gt=0).
  • docs/content/releases.md - the In the browser paragraph did not know the dataset screen carries recipes or exports by target.
  • docs/content/README.md - the releases.md row described publishing only; it now names the export half the page has carried since the epic.
  • docs/content/ui/product-principles.md - "the dataset's three views" is four.
  • docs/content/background-jobs.md - the export handler also resolves pre-processing drivers, through visionset.preprocessing.registry.
  • docs/content/architecture/backend/README.md - eight packages is nine; the stack diagram, the package table and the kernel-purity row did not know visionset.preprocessing exists.
  • docs/content/architecture/backend/kernel.md - the purity list and its rationale omitted preprocessing; the ports list omitted PreprocessingDriver; "the twelve services" is fifteen; the behaviour-page list gains preprocessing.md.
  • docs/content/architecture/backend/formats.md - said the surfaces resolve through registry.exporter(name), which is not what they call (pick, and resolve_target on the port); did not mention targets on the port; gains a section on the sibling visionset.preprocessing entry-point group, which the backend index links to.
  • docs/content/architecture/backend/cli.md - the same registry.exporter(name) claim.
  • docs/content/architecture/backend/server.md and mcp.md - the route-module and tool-module rosters lacked export targets, preprocessing recipes and (for MCP) inference.
  • docs/content/architecture/cross-cutting.md, AGENTS.md, .agents/skills/backend/kernel-architecture/SKILL.md - the kernel-purity contract as stated omitted visionset.preprocessing, which pyproject.toml has forbidden since the drivers landed.

Verified against code, and found current

The recipe grammar and its bounds (kernel/domain/preprocessing.py), the slug rule and the 512-pixel preview cap (preprocessing_recipe_service.py), the visionset recipe option grammar and the --spec-or-flags refusal (cli/preprocessing.py), --target/--format exclusivity and the stderr deprecation line (cli/export.py), the MCP tool names, the archive path <workspace>/exports/<release_id>/<format>/, migration 17 and the "sixteen entries after the baseline" count, the eleven-row visionset format list, the eight x-visionset-open vocabularies in openapi.json, the PUT rename-by-body shape and the ungated DELETE, the sitemap block and navigation.md against DatasetScreen.tsx's four tabs, and the sidebar entry for preprocessing.md.

Follow-ups

Published docstrings (routes and wire models) were read and none was found wrong, so openapi.json and the generated client are untouched. One non-published docstring recorded by the dialect work is still stale: formats/classification/__init__.py says the kernel enforces no (asset, class) uniqueness for a classification tag, while AnnotationService refuses a duplicate with DuplicateClassificationTag.

Checks

uv run python scripts/export_mcp_tools.py --check:

docs/content/mcp-tools.md matches the served tool listing.

uv run python scripts/export_target_catalog.py --check:

the export-target table in docs/content/releases.md matches the installed catalog.

uv run pytest tests/server/test_errors.py tests/architecture tests/formats/test_target_catalog_doc.py tests/mcp/test_tool_reference.py tests/kernel/test_migrations.py tests/cli/test_export_commands.py tests/test_versioning.py (there is no tests/docs directory; these are the tests that read docs/content):

167 passed in 34.32s

node --test tests/scripts/docs_links.test.mjs tests/scripts/docs_sidebar.test.mjs:

ℹ tests 11
ℹ pass 11
ℹ fail 0

bash scripts/check.sh docs:

All checks passed.
check.sh: PASSED  ran=docs  skipped=python,frontend,generated,browser

bash scripts/check.sh (the change touches AGENTS.md, a skill, README.md and CHANGELOG.md outside docs/):

4745 passed, 33 skipped in 42.70s
  281 passed (44.1s)
  1 passed (28.2s)
All checks passed.

check.sh: PASSED  ran=python,frontend,generated,browser  skipped=docs

The branch was then rebased onto main after the cycle-and-examples change (#802) and the export-dialog fix (#803) merged - no file overlaps - and bash scripts/check.sh docs was re-run on the rebased tree:

All checks passed.
check.sh: PASSED  ran=docs  skipped=python,frontend,generated,browser

…the code

Every page the two epics touched or should have touched, corrected where it
disagreed with main: the tutorial and README export by target, the changelog
gains the browser half of both epics and a Deprecated entry for the yolo
alias, the MCP counts and the REST route list catch up, and the architecture
pages, AGENTS.md and the kernel-architecture skill learn that
visionset.preprocessing exists and that the kernel may not import it.
@JArmandoAnaya
JArmandoAnaya merged commit ff94a70 into main Aug 26, 2026
15 checks passed
@JArmandoAnaya
JArmandoAnaya deleted the docs/export-targets-and-preprocessing branch August 26, 2026 12:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant