Skip to content

docs: fix incorrect claims, add missing tools, and release guide#193

Merged
vredchenko merged 1 commit intomainfrom
docs/audit-pr1-fix-incorrect-claims-and-release-guide
Apr 27, 2026
Merged

docs: fix incorrect claims, add missing tools, and release guide#193
vredchenko merged 1 commit intomainfrom
docs/audit-pr1-fix-incorrect-claims-and-release-guide

Conversation

@vredchenko
Copy link
Copy Markdown
Collaborator

Summary

PR 1 of the documentation audit (#187). Fixes factually incorrect content, fills completeness gaps, and adds a release procedure guide.

  • Fix ARIA definition in glossary — was incorrectly described as an image analysis system; now correctly describes it as a central metadata repository
  • Fix phantom tools in api-server.md — replaced nonexistent simulate_msg module and simulate-messages.sh with actual external_message_simulator.py; clarified dev-k8s.sh lives in smartem-devtools
  • Rewrite generate-docs.md — replaced stale tox -e docs reference with actual MDX sync + webui workflow
  • Fix database.md — enumerate all 6 migrations (was 3 + vague "apply remaining"); replace stale revision ID 6e6302f1ccb6 with actual migration filename
  • Add 4 undocumented tools to tools.md: check_schema_drift.py, db_table_totals.py, generate_api_docs.py, makeiso.sh
  • Add release procedure guide (docs/operations/releasing.md) covering smartem-decisions, smartem-epuplayer, and smartem-workspace — tag conventions, versioning, artifacts, manual releases, verification, uvx cache gotcha
  • Update operations index — link releasing and PyPI setup docs in toctree + Topics

Test plan

  • cd webui && npm run build passes — all docs sync and compile without errors
  • Visually check affected pages render correctly in dev server
  • Verify internal cross-links resolve (glossary, tools reference from api-server, releasing <-> pypi-publish)

Ref: #187

Fix factual errors identified in docs audit (#187):
- Correct ARIA definition (was claimed to be image analysis system)
- Replace phantom tools in api-server.md with actual simulator
- Rewrite generate-docs.md (was referencing nonexistent tox command)
- Fix database.md migration list (enumerate all 6, replace stale ID)
- Document 4 missing tools: check_schema_drift, db_table_totals,
  generate_api_docs, makeiso
- Add release procedure guide covering all 3 releasable packages
- Link releasing and PyPI setup docs in operations index
@vredchenko vredchenko added documentation Improvements or additions to project documentation smartem-devtools Developer tooling, documentation, and workspace configuration smartem-devtools:webui Developer dashboard web interface labels Apr 21, 2026
@vredchenko vredchenko merged commit 3f02f9b into main Apr 27, 2026
7 checks passed
@vredchenko vredchenko deleted the docs/audit-pr1-fix-incorrect-claims-and-release-guide branch April 27, 2026 12:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to project documentation smartem-devtools:webui Developer dashboard web interface smartem-devtools Developer tooling, documentation, and workspace configuration

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant