Generate SQLite Blueprints database schema documentation in markdown format with tables and Mermaid ER diagram showing table relationships and foreign keys.
Automatically generate nicely formatted markdown documentation of the Blueprints SQLite database, including detailed column definitions and visual relationship diagrams with foreign keys.
cd /root/xarta-node/.claude/skills/blueprints-schema-doc
./generate-schema-doc.sh
Output files are created in your current working directory:
blueprints-schema.md — Complete schema with all tables, columns, types, nullability, defaults, and relationshipsblueprints-schema-diagram.md — Mermaid ER diagram showing table structure and relationshipsA comprehensive markdown reference with:
→ nodes(node_id))Example table excerpt:
## `machines`
| Column | Type | Null? | Default | Notes |
|--------|------|:-----:|---------|-------|
| `machine_id` | `TEXT` | ✓ | — | **PK** |
| `name` | `TEXT` | ✗ | — | — |
| `parent_machine_id` | `TEXT` | ✓ | — | → `machines(machine_id)` |
| `created_at` | `TEXT` | ✓ | `datetime('now')` | — |
A Mermaid Entity-Relationship (ER) diagram showing:
machines ||--o{ machines)Foreign key relationships are inferred automatically by examining column naming patterns:
target_table_id → matched to target_tables table (handles irregular plurals)parent_machine_id → matched to machines tabletarget_node_id → matched to nodes tableExamples detected:
machines.parent_machine_id → machines.machine_id (self-reference)
sync_queue.target_node_id → nodes.node_id (external)
nodes.host_machine → (manual: not auto-detected)
services.host_machine → (manual: not auto-detected)
Note: host_machine references in nodes and services are not auto-detected because machines is not singular-pluralized conventionally. These can be manually documented if needed.
The script reads from: /opt/blueprints/data/db/blueprints.db
This is created and maintained by setup-blueprints.sh at runtime (not in git).
Run during documentation build steps:
bash /root/xarta-node/.claude/skills/blueprints-schema-doc/generate-schema-doc.sh
# Outputs to current dir; consider moving to docs/ folder
mv blueprints-schema*.md docs/
When a user asks to “show columns”, “what are the current columns”, or similar for the Blueprints database:
/opt/blueprints/data/db/blueprints.db.Column, Type, Null?, Default, Notes)generate-schema-doc.sh (or equivalent structured output), not plain lists.Minimum acceptable response shape:
## `table_name`
| Column | Type | Null? | Default | Notes |
|--------|------|:-----:|---------|-------|
| `id` | `TEXT` | ✗ | — | **PK** |
## Relationships Summary
- `child.parent_id` → `parent.id`
```mermaid
erDiagram
parent ||--o{ child : "references"
## MANDATORY - Embedded Menu DB Authority Contract (2026-04-08)
- Database is authoritative for embedded selector action pages in all contexts.
- `page_index` and `sort_order` from DB define order and slot positions.
- JS/runtime may insert placeholder circles only to preserve intentional DB slot gaps.
- Scarab paging control is always shown when multiple pages exist, except when touch ribbon mode is actively in use.
- Fallback is allowed only for embedded controls, and only when DB config fetch fails.
- Do not hardcode or merge local page layouts in a way that overrides DB-defined page order/positions.
## MANDATORY - App-Specific Selector Context Guardrail (2026-04-08)
- Never assume `menu_context='embed'` for new app work.
- Do not add or modify `embed_menu_items` rows in shared contexts (`embed`, `fallback-ui`, `db`) unless the user explicitly requests cross-app/shared rollout.
- Treat `embed` context as shared across all embed consumers (not app-local).
- For app-local selector behavior, require an app-specific context and explicit route-context wiring before any DB row additions.
- Default for new app work: no embed-menu DB writes unless explicitly requested.
The User insists on recognising that the menu system is database driven. Never use language that suggests otherwise such as setting defaults in a file. Word things carefully to always acknowledge that the menu system is database driven. Changes to icons for example happen in the database as paths. That is where to look. Always confirm any possible exceptions, with careful diplomacy and tone, with the User, before assuming there are.
The User insists on recognising that the menu system is database driven. Never use language that suggests otherwise such as setting defaults in a file. Word things carefully to always acknowledge that the menu system is database driven. Changes to icons for example happen in the database as paths. That is where to look. Always confirm any possible exceptions, with careful diplomacy and tone, with the User, before assuming there are.
When asked to commit and push ALL repos always including the lone wolf repo. Lone wolf repo is specific to each node and not distributed. Sometimes you'll be asked to also commit and push each lone wolf repo on each node separately via ssh. That is a separate concern to commit and push all repos.