@dboio/cli 0.19.0 → 0.19.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {

package/plugins/claude/dbo/.claude-plugin/plugin.json

@@ -1,8 +1,20 @@
 {
   "name": "dbo",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "DBO.io CLI integration for Claude Code",
   "author": {
     "name": "DBO.io"
-  }
+  },
+  "hooks": [
+    {
+      "path": "hooks/hooks.json"
+    }
+  ],
+  "skills": [
+    {
+      "path": "skills/white-paper/SKILL.md",
+      "name": "white-paper",
+      "description": "DBO project context and architecture guide — project structure, file-to-server mapping, dependencies, CLI vs API boundaries"
+    }
+  ]
 }

package/plugins/claude/dbo/README.md

@@ -0,0 +1,93 @@
+# DBO Plugin for Claude Code
+
+Claude Code plugin for the DBO.io platform. Provides project context, CLI command execution, and API reference for developing DBO applications.
+
+## Plugin Structure
+
+```
+dbo/
+├── .claude-plugin/
+│   └── plugin.json                 # Plugin manifest (version, hooks, skills)
+├── commands/
+│   └── dbo.md                      # /dbo slash command — CLI file operations
+├── hooks/
+│   └── hooks.json                  # SessionStart: auto-loads white-paper in DBO projects
+├── skills/
+│   └── white-paper/
+│       ├── SKILL.md               # Project architecture and context guide
+│       └── references/
+│           ├── api-reference.md   # REST API endpoint reference
+│           ├── template-syntax.md # Token, tag, and embed syntax
+│           └── deploy-and-scripts.md  # Deploy config and build pipeline
+├── docs/                          # Copied from api/docs/ at publish time (see below)
+└── README.md                      # This file
+```
+
+## Components
+
+### /dbo command (`commands/dbo.md`)
+User-invokable slash command for CLI operations. Handles file sync (push/pull/clone/add/rm/diff), deployment, and project setup. Restricted to CLI-appropriate tools via `allowed-tools`. Directs data read/write operations to the REST API instead.
+
+### SessionStart hook (`hooks/hooks.json`)
+Detects DBO projects by checking `.app/config.json` for an `AppUID` field. If found, auto-loads the white-paper skill to give Claude project context. This avoids false-matching other frameworks that may use `.app/` directories.
+
+### White paper skill (`skills/white-paper/SKILL.md`)
+Project architecture guide loaded at session start. Covers:
+- Directory structure and what maps to the server vs stays local
+- How `lib/` mirrors DBO table data (bin-based vs entity-based mapping)
+- Push/pull/deploy/clone workflow and supporting `.app/` config files (scripts, deploy_config, directories, schema)
+- `app_dependencies/` and how `_system` and parent app dependencies work
+- CLI vs REST API boundary (CLI for files, API for data)
+- Template variables (`{{domain}}`, `{{appName}}`, etc.) for per-project scaffolding
+
+### Reference files (`skills/white-paper/references/`)
+Deep-dive documentation that Claude reads on demand:
+
+| File | Content | Source of truth |
+|------|---------|-----------------|
+| `api-reference.md` | REST API endpoints, auth, filters, write syntax, curl examples | `api/docs/dbo-cheat-sheet.md` |
+| `template-syntax.md` | Token grammar, system tags, embed attributes, common patterns | `api/docs/dbo-cheat-sheet.md` |
+| `deploy-and-scripts.md` | Standard push/deploy/clone workflow; `.app/deploy_config.json` and `.app/scripts.json` details | Direct from CLI behavior and `.app/` file formats |
+
+## docs/ directory (bundled at publish)
+
+At npm publish time, `scripts/copy-plugins.js` copies `api/docs/` into `plugins/claude/dbo/docs/` so that documentation ships with the installed CLI package. This directory is NOT checked into the plugin source — it is generated.
+
+### Current docs source files (`api/docs/`)
+
+These are the canonical API documentation files. They are **actively being written** and may change:
+
+| File | Content |
+|------|---------|
+| `dbo-cheat-sheet.md` | Quick reference: primitives, tokens, tags, embeds, API, security |
+| `dbo-core-entities.md` | Schema reference for 38 core system entities |
+| `dbo-output-query.md` | Query output configuration and SQL mapping |
+| `dbo-output-customsql.md` | Custom SQL output type |
+
+### Updating references
+
+When `api/docs/` files are updated, the plugin reference files should be reviewed:
+
+1. **`api-reference.md`** — Derived from `dbo-cheat-sheet.md`. Update when endpoints, parameters, or auth patterns change.
+2. **`template-syntax.md`** — Derived from `dbo-cheat-sheet.md`. Update when token grammar, tags, or embed attributes change.
+3. **`deploy-and-scripts.md`** — Covers standard push/deploy/clone workflow and supporting `.app/` config files. Update when command behavior or config formats change.
+
+## Scaffolding (dbo init)
+
+The white-paper skill is designed to be scaffolded into each project's `.claude/` directory by `dbo init`. The CLI replaces template variables with app-specific values:
+
+| Variable | Source |
+|----------|--------|
+| `{{domain}}` | `.app/config.json` → `domain` |
+| `{{appName}}` | `.app/config.json` → `AppName` |
+| `{{appShortName}}` | `.app/config.json` → `AppShortName` |
+| `{{appUID}}` | `.app/config.json` → `AppUID` |
+| `{{appID}}` | `.app/config.json` → `AppID` |
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 0.8.2 | Added white-paper skill, SessionStart hook, reference files, deploy_config docs |
+| 0.8.1 | CLI skill with allowed-tools, CLI vs API boundary |
+| 0.6.3 | Initial CLI skill |

package/plugins/claude/dbo/commands/dbo.md

@@ -1,69 +1,57 @@
 ---
-name: cli
-description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — use docs/ for that.
-allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo add:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
+name: dbo
+description: Run DBO.io CLI commands for local file sync, project management, and deployment (push/pull/clone/add/rm/diff/build/deploy). NOT for direct API operations — for data reads/writes and runtime queries, use the REST API via curl with .app/cookies.txt instead.
+allowed-tools: Read, Write, Glob, Bash(git status:*), Bash(git branch:*), Bash(git diff:*), Bash(ls:*), Bash(dbo init:*), Bash(dbo login:*), Bash(dbo status:*), Bash(dbo deploy:*), Bash(dbo add:*), Bash(dbo clone:*), Bash(dbo push:*), Bash(dbo pull:*), Bash(dbo diff:*), Bash(dbo rm:*), Bash(dbo mv:*), Bash(dbo run:*), Bash(dbo install:*), Bash(dbo build:*), Bash(git stash:*), Bash(grep:*), Bash(which dbo:*)
 user-invokable: true
 ---
 
-# DBO CLI Skill
+# DBO CLI
 
-Run `dbo` CLI commands for local file sync, project management, and deployment.
+Run `dbo` CLI commands for local file operations, project management, and deployment.
 
-## When to use this skill
+## CLI vs REST API — When to use what
 
-Use this skill when the user wants to:
-- Run a local workflow command (push, pull, clone, add, rm, diff, build, deploy)
-- Set up a project (`dbo init`, `dbo login`, `dbo clone`)
-- Deploy files to the server (`dbo push`, `dbo deploy`)
+**Use this CLI skill for file operations:**
+- `pull`, `push`, `add`, `clone`, `rm`, `diff` — sync files between local project and server
+- `deploy` — push a file to DBO by UID or named shorthand (shorthands defined in `.app/deploy_config.json`)
+- `build`, `run` — compile source and run lifecycle scripts (configured in `.app/scripts.json`)
+- `init`, `login`, `status` — project setup and auth
 
-## When NOT to use this skill
+**Use the REST API directly (via curl) for data operations:**
+- Reading data: `curl -b .app/cookies.txt "https://{domain}/api/o/{uid}"`
+- Writing data: `curl -b .app/cookies.txt "https://{domain}/api/input/submit?_confirm=true" --data-urlencode 'RowID:...'`
+- Content retrieval, cache management, authentication, messaging, media access
 
-Do NOT use this skill for direct API operations. The following CLI commands are thin wrappers around REST endpoints — use the `docs/` reference instead for the canonical API syntax:
-- `dbo input` wraps `POST /api/input/submit` — use `docs/dbo-cheat-sheet.md`
-- `dbo output` wraps `GET /api/output/` — use `docs/dbo-output-query.md`
-- `dbo content` wraps `GET /api/content/` — use `docs/dbo-cheat-sheet.md`
-- `dbo media` wraps `GET /api/media/` — use `docs/dbo-cheat-sheet.md`
-- `dbo upload` wraps `POST /api/upload/submit` — use `docs/dbo-cheat-sheet.md`
-- `dbo message` wraps `GET /api/message/` — use `docs/dbo-cheat-sheet.md`
-- `dbo cache` wraps `/api/cache/` — use `docs/dbo-cheat-sheet.md`
+The CLI wraps some API endpoints (`dbo input`, `dbo output`, `dbo content`, `dbo media`, `dbo cache`, `dbo upload`, `dbo message`) but these are thin wrappers — prefer direct REST API calls for data reads/writes as they give full control over parameters. Reference the white-paper skill's `references/api-reference.md` for endpoint documentation.
 
-Also do NOT use this skill for:
-- **Entity schemas / column names** — use `docs/dbo-core-entities.md`
-- **Token/tag syntax** (`#{...}`, `<#_embed>`, etc.) — use `docs/dbo-cheat-sheet.md`
-- **Building server-side templates or content records** — use `docs/`
-
-All doc files are bundled in the `docs/` subdirectory of this plugin (copied during npm publish). When working in the repo, the API docs are at the repo root `docs/` and the CLI README is at `tools/cli/README.md`.
-
-For detailed CLI command flags, options, and behavior — read `docs/dbo-cli-readme.md`.
+For entity schemas, column names, token/tag syntax, and template authoring — read the `docs/` directory bundled with this plugin (or `references/template-syntax.md` from the white-paper skill).
 
 ## Running commands
 
-**If `$ARGUMENTS` is empty**, show the command table and guide interactively.
+**If `$ARGUMENTS` is empty**, show the command table below and guide interactively. Run `dbo status` proactively to check if the CLI is initialized and authenticated.
 
-**If `$ARGUMENTS` is provided**, check if command exists in the command table in the available commands (use best guess, eg: initialize => init), then on match run the command:**:
+**If `$ARGUMENTS` is provided**, match against the command table (use best guess, e.g., "initialize" → `init`, "upload files" → `push`), then run:
 
 ```bash
 dbo $ARGUMENTS
 ```
 
-## Command overview
-
-These are the local workflow commands this skill covers:
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `init` | Initialize .dbo/ configuration |
+| `init` | Initialize `.app/` configuration |
 | `login` / `logout` | Authenticate / clear session |
 | `status` | Show config, domain, session info |
-| `clone` | Clone an app to local project |
+| `clone` | Clone an app to local project structure |
 | `pull` | Pull records to local files |
-| `push` | Push local changes (default: current dir) |
+| `push` | Push local changes to server |
 | `add` | Add a new file to DBO.io |
-| `diff` | Compare local vs server |
-| `rm` | Remove file, stage server deletion |
-| `deploy` | Deploy via .dbo/deploy_config.json manifest |
-| `build` | Run build hooks (.dbo/scripts.json) |
-| `run` | Run named script (.dbo/scripts.json) |
+| `diff` | Compare local files vs server versions |
+| `rm` | Remove file and stage server deletion |
+| `deploy` | Push a file to DBO by UID or named shorthand |
+| `build` | Run build hooks from `.app/scripts.json` |
+| `run` | Run a named script from `.app/scripts.json` |
 | `install` | Install/upgrade CLI, plugins (alias: `i`) |
 
 ## Common workflows
@@ -76,7 +64,7 @@ dbo login
 # Edit and push
 dbo push                          # push all changes in current dir
 dbo push lib/bins/app/assets/     # push specific directory
-dbo push colors.css               # push single file
+dbo push colors.css               # push single file (auto-finds in project)
 
 # Build and push (with script hooks)
 dbo build                         # run build hooks only
@@ -84,6 +72,10 @@ dbo push                          # build + push (hooks run automatically)
 dbo push --no-build               # push without build phase
 dbo push --no-scripts             # push without any hooks
 
+# Deploy by shorthand or UID
+dbo deploy css:colors             # deploy using deploy_config.json shorthand
+dbo deploy albain3dwkofbhnd1qtd1q # deploy by UID directly
+
 # Pull
 dbo pull -e content --filter 'AppID=10100'
 

package/plugins/claude/dbo/hooks/hooks.json

@@ -0,0 +1,11 @@
+{
+  "description": "DBO plugin hooks — auto-loads project context on session start",
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "prompt",
+        "prompt": "Check if this is a DBO project by reading .app/config.json. If the file exists and contains an 'AppUID' field, this is a DBO project — invoke the /dbo:white-paper skill to load project context silently. If .app/config.json does not exist or has no AppUID field, do nothing."
+      }
+    ]
+  }
+}

package/plugins/claude/dbo/skills/white-paper/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: white-paper
+description: >-
+  DBO project context and architecture guide. This skill should be loaded at
+  SessionStart or when Claude needs to understand a DBO project's structure,
+  metadata, file mapping, dependencies, CLI vs API boundaries, or the
+  relationship between local files and the DBO server. Triggers on project
+  exploration, architecture questions, or when working with .app/, lib/, docs/,
+  app_dependencies/, src/, or test/ directories.
+user-invokable: true
+---
+
+# DBO Project White Paper
+
+This skill provides architectural context for working within a DBO.io project. Read this to understand the local project structure, how files map to server records, when to use the CLI vs the REST API, and how dependencies work.
+
+For deeper reference, consult these companion files:
+- `references/api-reference.md` — Full REST API endpoint reference
+- `references/template-syntax.md` — Token, tag, and embed syntax
+- `references/deploy-and-scripts.md` — Standard push/deploy/clone workflow and supporting config details
+
+## Core Principle
+
+DBO is a schema-driven application framework. The database schema IS the application. There is no traditional middle tier — apps are defined through entity records, templates, security rules, and metadata. The local project mirrors the server's data model as files on disk.
+
+## Project Identity
+
+When scaffolded by `dbo init`, the CLI injects these app-specific values:
+- **Domain**: `{{domain}}`
+- **App**: `{{appName}}` (`{{appShortName}}`)
+- **AppUID**: `{{appUID}}`
+- **AppID**: `{{appID}}`
+
+## Project Directory Map
+
+```
+project-root/
+├── .app/                    # App metadata and configuration (DBO-managed)
+│   ├── config.json          # Domain, AppID, AppUID, settings, dependency versions
+│   ├── {app}.json           # Complete app data export (read-only reference)
+│   ├── {app}.metadata.json  # App-level metadata
+│   ├── {app}.metadata_schema.json  # Database schema for this app
+│   ├── scripts.json         # Build/postpush script definitions
+│   ├── deploy_config.json   # Deployment shorthand targets (see Deploy section)
+│   ├── directories.json     # BinID → directory path mapping
+│   ├── credentials.json     # Auth credentials (gitignored)
+│   └── cookies.txt          # Session cookies (gitignored)
+│
+├── lib/                     # Server-mapped files (mirrors DBO table data)
+│   ├── bins/                # Bin entities and their children (see Bin Mapping below)
+│   ├── extension/           # Extension records, sub-foldered by Descriptor
+│   ├── entity/              # Entity metadata files
+│   ├── site/                # Site definitions
+│   ├── security/            # Security rule records
+│   ├── data_source/         # Data source configurations
+│   └── app_version/         # App version metadata
+│
+├── docs/                    # Project documentation (scripts, embeds, pages, components)
+├── app_dependencies/        # Cloned dependency apps (read-only references)
+│   ├── _system/             # Always present — core DBO platform schema
+│   └── {app_name}/          # Present when developing a dependency app
+│
+├── src/                     # Developer source (NEVER uploaded to server)
+├── test/                    # Test scripts (NEVER uploaded to server)
+├── trash/                   # Archived files (NEVER uploaded to server)
+└── node_modules/            # NPM packages (NEVER uploaded to server)
+```
+
+**Key rule:** Only `lib/` and `docs/` contents map to the DBO server. The `src/`, `test/`, `trash/`, and `node_modules/` directories are strictly local — nothing inside them is ever deployed or uploaded.
+
+## How lib/ Maps to the Server
+
+The `lib/` directory emulates the server's table data as a local file structure.
+
+### Bin-based entities (have BinID or ParentBinID columns)
+
+Files belonging to a `bin` entity are placed in directories matching their BinID. The mapping is defined in `.app/directories.json`, which maps numeric BinIDs to directory paths:
+
+```json
+{
+  "11042": { "name": "app", "fullPath": "app", "binId": 11042 },
+  "11043": { "name": "assets", "fullPath": "app/assets", "parentBinID": 11042 }
+}
+```
+
+So `lib/bins/app/assets/css/colors.css` lives inside the bin whose `fullPath` is `app/assets/css`. Every file has a companion `.metadata.json` (or `.metadata~{uid}.json`) containing the server record fields.
+
+### Non-bin entities (no BinID column)
+
+Entities without a BinID column get their own directory under `lib/`, named after the entity: `lib/extension/`, `lib/entity/`, `lib/site/`, `lib/security/`, `lib/data_source/`, `lib/app_version/`.
+
+### Extension special case
+
+The `extension` entity has sub-folders based on the **Descriptor** column value:
+- `lib/extension/Control/` — Control extensions
+- `lib/extension/Widget/` — Widget extensions
+- `lib/extension/Descriptor Definition/` — Descriptor definitions themselves
+
+Each extension file follows: `{Name}.{ContentColumnName}.{ext}` with a companion `{Name}.metadata~{uid}.json`.
+
+## .app/ Configuration
+
+### config.json
+Central project configuration. Key fields:
+- `domain` — Server hostname for API calls
+- `AppID`, `AppUID`, `AppShortName` — App identity
+- `dependencies` — Array of dependency app names (always includes `_system`)
+
+### scripts.json
+Defines build and deployment scripts per target file:
+- `build` scripts compile source → output (e.g., sass, rollup, csso)
+- `postpush` scripts run after `dbo push` (e.g., `dbo deploy doc:chat`)
+- `entities` object can define per-entity scripts
+
+See `references/deploy-and-scripts.md` for full details.
+
+### deploy_config.json
+Optional shorthand registry for `dbo deploy`. Auto-generated by `dbo clone` and `dbo adopt` — one entry per companion file.
+
+```bash
+dbo deploy css:colors              # Deploy by shorthand name
+dbo deploy albain3dwkofbhnd1qtd1q  # Deploy by UID directly (no config needed)
+```
+
+Each entry maps a shorthand to a UID, file path, entity, and content column. Shorthands follow `{type}:{name}` convention (e.g., `css:colors`, `js:app.min`). Assets often have paired content + media records (e.g., `css:colors` and `css:colors_media`).
+
+See `references/deploy-and-scripts.md` for full details.
+
+### directories.json
+Maps BinIDs to local directory paths. Used by CLI to place files during `clone` and `pull`, and to resolve which bin a file belongs to for `push` and `add`.
+
+### metadata_schema.json
+Database schema definition for this app. Derived from `_system` core entities plus app-specific entities. Use this to understand available tables, columns, data types, and relationships.
+
+## Dependencies (app_dependencies/)
+
+### _system (always present)
+Contains the core DBO platform schema — all system entities, tables, columns, and foundational architecture. Defines:
+- Core entities (app, user, content, media, output, entity, etc.)
+- System schema used to build `.app/{app}.metadata_schema.json`
+- Platform-level documentation in `app_dependencies/_system/docs/`
+
+### {app_name} dependency (when present)
+When `app_dependencies/{app_name}/` exists (e.g., `app_dependencies/operator/`), the current project is a **dependency app** to that parent. This means:
+
+1. **Extension descriptor mapping** — Check `app_dependencies/{app_name}/lib/extension/Descriptor Definition/` for `extension.Descriptor=descriptor_definition` files. These define the descriptor types available for extensions in the current project.
+
+2. **Design resources** — `app_dependencies/{app_name}/lib/bins/app/assets/` contains CSS, JS, fonts, graphics, and templates defining the parent app's design language. Reference these for consistent styling.
+
+3. **Architecture reference** — The parent app's structure, scripts, and layout patterns inform what the current project needs to implement.
+
+## CLI vs REST API
+
+### Use the DBO CLI for:
+- **File operations**: `pull`, `push`, `add`, `clone`, `rm`, `diff`
+- **Deployment**: `deploy` (shorthand or UID), content deploy
+- **Project setup**: `init`, `login`, `status`
+- **Batch operations**: pushing directories, scanning for un-added files
+
+The CLI handles metadata management, change detection, and file-to-record synchronization automatically.
+
+### Use the REST API for:
+- **Data reads/queries**: `GET /api/o/{uid}`, `GET /api/output/entity/{entityUid}`
+- **Data writes**: `POST /api/input/submit` with RowID syntax
+- **Content retrieval**: `GET /api/c/{uid}`
+- **Runtime operations**: cache management, authentication, email/messaging
+- **Media access**: `GET /api/media/{uid}`
+
+See `references/api-reference.md` for full endpoint documentation.
+
+### API authentication
+Credentials and cookies in `.app/credentials.json` and `.app/cookies.txt`. CLI manages via `dbo login`. For direct API calls:
+```bash
+curl -b .app/cookies.txt "https://{{domain}}/api/output/entity/{uid}"
+```
+
+### API write syntax (input/submit)
+```
+RowID:add1;column:entity.Column=value          # Insert
+RowID:{id};column:entity.Column=value           # Update
+RowID:del{id};entity:entityName=true            # Delete
+```
+Always include `_confirm=true`. Special values: `_{now}` (datetime), `_{null}` (null).
+
+## docs/ Directory
+
+Contains Markdown documentation for this project's components — scripts, embeds, pages, UI features. These are project-specific references generated or maintained alongside development. Read these to understand documented behaviors of the current app.
+
+## Build Pipeline
+
+Source files in `src/` compile via scripts in `.app/scripts.json`:
+- **build** scripts: Run manually or via `npm run build`
+- **postpush** scripts: Run automatically after `dbo push` for specific targets
+
+Common tools: `rollup` (JS bundling), `sass` (CSS), `csso` (CSS minification), `terser` (JS minification).
+
+Use `dbo push` to trigger builds automatically (runs `build` then pushes), or `dbo build` to compile without pushing. See `references/deploy-and-scripts.md` for the full workflow.
+
+## Test Directory
+
+The `test/` directory is for developer and Claude Code test scripts. Tests target the app but are never uploaded to the server. Use for:
+- API integration tests
+- UI component tests
+- Build verification scripts
+- Any validation logic for the project
+
+## Quick Reference
+
+| Task | Tool | Example |
+|------|------|---------|
+| Query data | REST API | `GET /api/o/{uid}` |
+| Read entity rows | REST API | `GET /api/output/entity/{entityUid}` |
+| Write/update data | REST API | `POST /api/input/submit` |
+| Pull files from server | CLI | `dbo pull -e content` |
+| Push local changes | CLI | `dbo push path/to/file` |
+| Add new file to server | CLI | `dbo add path/to/file` |
+| Deploy by shorthand | CLI | `dbo deploy css:colors` |
+| Deploy by UID | CLI | `dbo deploy {uid}` |
+| Compare with server | CLI | `dbo diff` |
+| Build from source | npm/scripts | Commands from `.app/scripts.json` |
+| Understand schema | Read file | `.app/{app}.metadata_schema.json` |
+| Find bin for a path | Read file | `.app/directories.json` |
+| Check deploy targets | Read file | `.app/deploy_config.json` |
+| Check project config | Read file | `.app/config.json` |
+| Understand dependencies | Read dir | `app_dependencies/` |

package/plugins/claude/dbo/skills/white-paper/references/api-reference.md

@@ -0,0 +1,172 @@
+# DBO REST API Reference
+
+Comprehensive reference for the DBO.io REST API. Use this when constructing API calls, debugging responses, or understanding the data model.
+
+## Authentication
+
+### Endpoint
+```
+GET /api/authenticate?action=login
+GET /api/authenticate?action=logout
+```
+
+### Identity parameters (pick one)
+| Param | Short | Column |
+|-------|-------|--------|
+| `_username` | `_un` | `user.Username` |
+| `_email` | `_em` | `user.Email` |
+| `_phonenumber` | `_pn` | `user.PhoneNumber` |
+
+### Credential parameters
+| Param | Short | Column |
+|-------|-------|--------|
+| `_password` | `_pw` | `user.Password` |
+| `_passkey` | `_pk` | `user.Passkey` |
+
+Auth parameters can be sent on ANY endpoint with `_login=true` to authenticate inline.
+
+## Read Operations
+
+### Output query
+```
+GET /api/output/{uid}
+GET /api/o/{uid}                    # shorthand
+```
+
+### Entity query (direct table access)
+```
+GET /api/output/entity/{entityUid}
+GET /api/output/entity/{entityUid}/{rowId}
+```
+
+For system entities, `{entityUid}` is the table name: `content`, `user`, `output`, `media`, `entity`, `entity_column`, `extension`, `site`, `bin`, `security`, etc.
+
+### Content
+```
+GET /api/content/{uid}
+GET /api/c/{uid}                    # shorthand
+```
+
+### Media
+```
+GET /api/media/{uid}
+GET /api/media/id/{id}
+GET /dir/{*path}                    # direct path access
+```
+
+### Filter and control parameters
+| Param | Effect |
+|-------|--------|
+| `_filter@Field=value` | Dynamic row filter |
+| `_filter@Field:restrictive=value` | Non-overridable filter |
+| `_limit=N` | Max rows returned |
+| `_page=N` | Pagination |
+| `_template=json_indented` | Override output format (json_indented, html, xml, csv) |
+| `voidcache=true` | Flush all caches globally |
+| `_debug=true` | Enable debug output |
+| `_as={userId}` | Impersonate user (render context only, not security) |
+
+## Write Operations
+
+### Input submit
+```
+POST /api/input/submit?_confirm=true
+```
+
+`_confirm=true` is REQUIRED for any write to execute.
+
+### Row syntax
+```
+RowID:{ref};column:{entity}.{Column}={value}
+```
+
+### Reference types
+| Ref | Operation |
+|-----|-----------|
+| `add1`, `add2`, … | Insert new record |
+| `{id}` or `{uid}` | Update existing record |
+| `del{id}` | Delete record |
+
+`RowID:` and `RowUID:` are interchangeable. Use `RowUID:` for cross-environment stability.
+
+### Cross-referencing within a batch
+```
+RowID:add1;column:parent_table.Name=Test
+RowID:add2;column:child_table.ParentID=add1
+```
+
+### Special values
+| Value | Meaning |
+|-------|---------|
+| `_{now}` | Current datetime (server resolves) |
+| `_{null}` | Null / empty value |
+
+### curl example
+```bash
+curl -b .app/cookies.txt \
+  'https://{domain}/api/input/submit?_confirm=true' \
+  --data-urlencode 'RowID:add1;column:content.Name=my-page' \
+  --data-urlencode 'RowID:add1;column:content.Content=<h1>Hello</h1>' \
+  --data-urlencode 'RowID:add1;column:content.AppID=10100'
+```
+
+## Cache Management
+
+```
+GET /api/cache/list
+GET /api/cache/refresh?_key=output:meta:{uid}
+GET /api/cache/refresh?_key=secure:output:meta:{uid}
+```
+
+## Upload
+
+```
+POST /api/upload/submit
+```
+
+File upload with multipart form data. Metadata can be attached.
+
+## Email / Messaging
+
+```
+GET /api/content/email/{uid}
+GET /api/message/content/{uid}
+POST /api/message/receive/{messageServerUid}
+```
+
+## Data Source
+
+```
+POST /api/data_source/metadata/synchronize/{dataSourceUid}
+POST /api/data_source/metadata/synchronize/in/{dataSourceUid}
+POST /api/data_source/metadata/synchronize/out/{dataSourceUid}
+```
+
+## App Lifecycle
+
+```
+GET  /api/app/export/{appUid}
+POST /api/app/import/{appUid}
+GET  /api/app/delete/{appUid}
+POST /api/app_version/populate/{appVersionUid}
+POST /api/app_version/clear/{appVersionUid}
+```
+
+## Instance Management
+
+```
+GET  /api/instance/debug
+POST /api/instance/export
+POST /api/instance/import
+POST /api/instance/generate/{accountUid}
+POST /api/instance/build/{instanceUid}
+```
+
+## Identifiers
+
+- **UID** (22-char alphanumeric): Stable across environments. Use in templates, tokens, deploy scripts.
+- **Numeric ID**: Environment-specific. May change across migrations. Use only for runtime lookups.
+
+### Column UID patterns
+- **System entities**: `{entity}.{ColumnName}` (e.g., `content.Content`, `media.File`)
+- **Custom entities**: Opaque UIDs — discover via `GET /api/output/entity/{entityUid}?_template=json_indented&_limit=1`