@dboio/cli 0.6.14 → 0.8.0

package/README.md

@@ -98,6 +98,9 @@ dbo --version
 # 1. Initialize configuration for the current directory
 dbo init --domain my-domain.com
 
+# 1b. Combined with cloning an app to local project bin
+dbo init --domain my-domain.com --app myapp --clone
+
 # 2. Authenticate
 dbo login
 
@@ -144,6 +147,7 @@ All configuration is **directory-scoped**. Each project folder maintains its own
   "AppUID": "abc123",
   "AppName": "My App",
   "AppShortName": "myapp",
+  "cloneSource": "default",
   "ContentPlacement": "bin",
   "MediaPlacement": "fullpath"
 }
@@ -158,6 +162,8 @@ All configuration is **directory-scoped**. Each project folder maintains its own
 | `AppShortName` | string | App short name (used for `dbo clone --app`) |
 | `AppModifyKey` | string | ModifyKey for locked/production apps (set by `dbo clone`, used for submission guards) |
 | `TransactionKeyPreset` | `RowUID` \| `RowID` | Row key type for auto-assembled expressions (set during `dbo init`/`dbo clone`, default `RowUID`) |
+| `TicketSuggestionOutput` | string | Output UID for fetching ticket suggestions during error recovery (set during `dbo init`, default `ojaie9t3o0kfvliahnuuda`) |
+| `cloneSource` | `"default"` \| file path \| URL | Where the last `dbo clone` fetched app JSON from. `"default"` = server fetch via `AppShortName`; any other value = the explicit local file path or URL used. Set automatically after each successful clone. |
 | `ContentPlacement` | `bin` \| `path` \| `ask` | Where to place content files during clone |
 | `MediaPlacement` | `bin` \| `fullpath` \| `ask` | Where to place media files during clone |
 | `<Entity>FilenameCol` | column name | Filename column for entity-dir records (e.g., `ExtensionFilenameCol`) |
@@ -173,6 +179,41 @@ These are set interactively on first clone and saved for future use. Pre-set the
 
 The `_domain` field in `app.json` stores the project's reference domain (set during `dbo clone`). This is committed to git and used for domain-change detection when running `dbo init --force` or `dbo clone --domain`. It provides a stable cross-user baseline — all collaborators share the same reference domain.
 
+### `.dboignore`
+
+A gitignore-style file in the project root that controls which files and directories are excluded from CLI operations. Created automatically by `dbo init` with sensible defaults.
+
+**Used by:**
+- `dbo init` — scaffold empty-check (determines if directory is "effectively empty")
+- `dbo add .` — directory scanning (which files/dirs to skip)
+- `dbo push` — metadata file discovery (which dirs to skip)
+
+**Syntax:** Same as `.gitignore` — glob patterns, `#` comments, blank lines, negation with `!`, directory-only patterns with trailing `/`.
+
+**Default patterns:**
+
+```gitignore
+.dbo/              # DBO internal
+*.dboio.json       # Export files
+app.json           # Clone output
+.app.json          # Clone baseline
+dbo.deploy.json    # Deployment manifest
+.git/              # Version control
+.gitignore
+node_modules/      # Node
+package.json
+package-lock.json
+.claude/           # AI / tooling
+.mcp.json
+.idea/             # Editor / IDE
+.vscode/
+*.codekit3
+README.md          # Repo scaffolding
+SETUP.md
+```
+
+Edit `.dboignore` to add or remove patterns. Committed to git and shared across users.
+
 ### Legacy migration
 
 If your project uses the older `.domain`, `.username`, `.password`, `.cookies` files, `dbo init` will detect them and offer to migrate automatically.
@@ -214,6 +255,7 @@ dbo init --scaffold --yes                             # scaffold dirs non-intera
 | `-g, --global` | Install Claude commands globally (`~/.claude/commands/`) |
 | `--local` | Install Claude commands to project (`.claude/commands/`) |
 | `--scaffold` | Pre-create standard project directories (`App Versions`, `Automations`, `Bins`, `Data Sources`, `Documentation`, `Extensions`, `Groups`, `Integrations`, `Sites`) |
+| `--dboignore` | Create `.dboignore` with default patterns (use with `--force` to overwrite existing) |
 | `-y, --yes` | Skip all interactive prompts (legacy migration, Claude Code setup) |
 | `--non-interactive` | Alias for `--yes` |
 
@@ -235,14 +277,24 @@ dbo clone --app myapp
 
 # Combined with init
 dbo init --domain my-domain.com --app myapp --clone
+
+# Extension descriptor sub-directory handling
+dbo clone -e extension                            # Clone all extensions (sorted by descriptor type)
+dbo clone -e extension --documentation-only       # Clone only documentation extensions
+dbo clone -e extension --documentation-only --force  # Reset documentation preferences and re-clone
+dbo clone -e extension --descriptor-types false   # Clone extensions flat (no descriptor sorting)
 ```
 
 | Flag | Description |
 |------|-------------|
-| `<source>` | Local JSON file path (optional positional argument) |
+| `<source>` | Local file path or URL to load app JSON from (optional positional argument) |
 | `--app <name>` | App short name to fetch from server |
+| `-e, --entity <type>` | Only clone a specific entity type (e.g. `output`, `content`, `media`, `extension`) |
+| `--documentation-only` | When used with `-e extension`, clone only documentation extensions |
+| `--descriptor-types <bool>` | Sort extensions into descriptor sub-directories (default: `true`). Set to `false` to use flat `Extensions/` layout |
 | `--domain <host>` | Override domain. Triggers a domain-change confirmation prompt when it differs from the project reference domain |
-| `-y, --yes` | Auto-accept all prompts |
+| `--force` | Skip source mismatch confirmation and change detection; re-processes all files |
+| `-y, --yes` | Auto-accept all prompts (also skips source mismatch confirmation) |
 | `-v, --verbose` | Show HTTP request details |
 
 #### Domain change detection
@@ -254,7 +306,7 @@ The project's reference domain is stored in `app.json._domain` (committed to git
 #### What clone does
 
 1. **Loads app JSON** — from a local file, server API, or interactive prompt
-2. **Updates `.dbo/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`, and `AppModifyKey` (if the app is locked)
+2. **Updates `.dbo/config.json`** — saves `AppID`, `AppUID`, `AppName`, `AppShortName`, `AppModifyKey` (if the app is locked), and `cloneSource` (the source used for this clone)
 3. **Updates `package.json`** — populates `name`, `productName`, `description`, `homepage`, and `deploy` script
 4. **Creates directories** — processes `children.bin` to build the directory hierarchy based on `ParentBinID` relationships
 5. **Saves `.dbo/structure.json`** — maps BinIDs to directory paths for file placement
@@ -264,6 +316,30 @@ The project's reference domain is stored in `app.json._domain` (committed to git
 9. **Processes other entities** — remaining entities with a `BinID` are placed in the corresponding bin directory
 10. **Saves `app.json`** — clone of the original JSON with processed entries replaced by `@path/to/*.metadata.json` references
 
+#### Clone source tracking
+
+After every successful clone, the source is persisted as `cloneSource` in `.dbo/config.json`:
+
+- `"default"` — app JSON was fetched from the server using `AppShortName` (the normal flow)
+- A file path or URL — set when an explicit `<source>` argument was provided (e.g. `dbo clone /path/to/export.json`)
+
+On subsequent clones, if you provide an explicit source that **differs** from the stored `cloneSource`, the CLI warns and asks for confirmation before proceeding:
+
+```
+  ⚠  This project was previously cloned from: default
+     Requested source:                        /path/to/export.json
+? Clone from the new source anyway? This will update the stored clone source. (y/N)
+```
+
+Use `--force` or `-y` to skip the prompt and override without being asked.
+
+If the initial clone attempt fails (network error, file not found, empty response), the CLI prompts for a fallback source to retry with instead of aborting:
+
+```
+  ⚠  Source did not return expected results: No app found with ShortName "myapp"
+? Enter another local file path or URL to retry (or leave empty to abort):
+```
+
 #### Change detection on re-clone
 
 When cloning an app that was already cloned locally, the CLI detects existing files and compares modification times against the server's `_LastUpdated`. You'll be prompted to overwrite, compare differences, or skip — same as `dbo pull`. Use `-y` to auto-accept all changes.
@@ -311,7 +387,7 @@ Entity types that correspond to project directories (`extension`, `app_version`,
 
 | Entity Key | Directory |
 |------------|-----------|
-| `extension` | `Extensions/` |
+| `extension` | `Extensions/<Descriptor>/` (see below) |
 | `app_version` | `App Versions/` |
 | `data_source` | `Data Sources/` |
 | `site` | `Sites/` |
@@ -325,6 +401,44 @@ If any columns contain base64-encoded content, the CLI prompts to extract them a
 
 Use `-y` to skip prompts (uses `Name` column, no content extraction).
 
+#### Extension descriptor sub-directories
+
+Extension records are organized into sub-directories under `Extensions/` based on their `Descriptor` column value. A special extension type called `descriptor_definition` (itself an extension with `Descriptor === "descriptor_definition"`) provides the mapping from descriptor key (`String1`) to display/directory name (`Name`).
+
+During clone, the CLI:
+
+1. **Pre-scans** all extension records for `descriptor_definition` entries and builds a `String1 → Name` mapping
+2. **Creates sub-directories** under `Extensions/` for each mapped descriptor (e.g., `Extensions/Documentation/`, `Extensions/Includes/`)
+3. **Always creates** `Extensions/Unsupported/` — extensions with an unmapped or null `Descriptor` are placed here
+4. **Prompts per descriptor** — filename column and content extraction prompts fire once per unique `Descriptor` value (not once for all extensions)
+5. **Persists the mapping** in `.dbo/structure.json` under `descriptorMapping`
+
+**Config keys** (saved per descriptor in `config.json`):
+
+| Key | Example | Purpose |
+|-----|---------|---------|
+| `Extension_<descriptor>_FilenameCol` | `Extension_documentation_FilenameCol` | Filename column for that descriptor type |
+| `Extension_<descriptor>_ContentExtractions` | `Extension_documentation_ContentExtractions` | Content extraction preferences per column |
+| `ExtensionDocumentationMDPlacement` | `"inline"` or `"root"` | Where to place documentation MD files |
+
+**Documentation alternate placement**: When extracting MD content from `documentation` descriptor extensions, the CLI offers a choice:
+
+- **Root placement** (`/Documentation/<filename>.md`) — recommended for easy access; creates `@/Documentation/<filename>.md` references in metadata
+- **Inline placement** (`Extensions/Documentation/<filename>.md`) — keeps files alongside metadata
+
+Root-placed files use absolute-from-root `@/` references (e.g., `@/Documentation/my-doc.md`) so `dbo push` can locate them regardless of where the metadata lives.
+
+**Entity filter support**:
+
+```bash
+dbo clone -e extension --documentation-only         # Clone only documentation extensions
+dbo clone -e extension --documentation-only --force  # Reset documentation preferences and re-clone
+dbo clone -e extension                               # Clone all extensions (all descriptor types)
+dbo clone -e extension --descriptor-types false       # Flat layout (no descriptor sorting)
+```
+
+**`dbo add` auto-inference**: Running `dbo add Documentation/my-doc.md` when `ExtensionDocumentationMDPlacement` is `"root"` auto-creates a companion `.metadata.json` in `Extensions/Documentation/` with the correct `@/` reference.
+
 #### Output structure
 
 ```
@@ -343,9 +457,15 @@ project/
       CurrentTicketID.metadata.json
     ticket_test/             # ← another bin directory
       ...
-  Extensions/                # ← entity-dir records
-    MyExtension.metadata.json
-    MyExtension.CustomCSS.css    # ← extracted content column
+  Extensions/                # ← extension records organized by descriptor
+    Documentation/           # ← descriptor sub-directory (from descriptor_definition)
+      MyDoc.uid1.metadata.json
+      MyDoc.uid1.String10.md     # ← extracted content column
+    Includes/
+      Header.uid2.metadata.json
+    Unsupported/             # ← always created (unmapped/null descriptors)
+  Documentation/             # ← root-placed documentation MD files (optional)
+    MyDoc.md
   Data Sources/
     MySQL-Primary.metadata.json
   Sites/
@@ -571,8 +691,24 @@ dbo output myOutputUID --debug-sql
 | `--maxrows <n>` | Maximum rows |
 | `--rows <range>` | Row range, e.g., `1-10` |
 | `--template <value>` | Custom template |
+| `--limit <n>` | Maximum rows to return (preferred over `--maxrows`) |
+| `--rowcount <bool>` | Include row count: `true` (default) or `false` for performance |
+| `--display <expr>` | Show/hide template tags (repeatable), e.g., `sidebar=hide` |
+| `--format-values` | Enable value formatting in `json_raw` output |
+| `--empty-response-code <code>` | HTTP status code when output returns no results |
+| `--fallback-content <expr>` | Fallback content UID for error codes, e.g., `404=contentUID` |
+| `--escape-html <bool>` | Control HTML escaping: `true` or `false` |
+| `--mime <type>` | Override MIME/content type |
+| `--strict` | Strict error mode |
+| `--confirm` | Confirmation flag |
+| `--include <expr>` | Include token |
+| `--no-transaction` | Disable transaction wrapping |
+| `--skip <phase>` | Skip execution phases (repeatable, admin-only) |
+| `--profile` | Enable MiniProfiler output |
 | `--debug` | Include debug info |
 | `--debug-sql` | Include SQL debug info |
+| `--debug-verbose` | Verbose debug output |
+| `--debug-analysis` | Analysis debug output |
 | `--meta` | Use meta output endpoint |
 | `--meta-column <uid>` | Column metadata |
 | `--save` | Interactive save-to-disk mode |
@@ -1156,6 +1292,22 @@ When the server returns a `ticket_error` (record update requires a Ticket ID), t
   Skip all updates that require a Ticket ID
 ```
 
+#### Ticket suggestions
+
+When `TicketSuggestionOutput` is configured in `.dbo/config.json` (set during `dbo init`), the CLI automatically fetches relevant ticket suggestions from the server and presents them as selectable choices:
+
+```
+? Select a Ticket ID:
+❯ 1 (TKT-001): Fix login page [login-fix]
+  2 (TKT-002): Update dashboard [dashboard-v2]
+  3 (TKT-003): Refactor auth [auth-refactor]
+  Enter a Ticket ID manually…
+```
+
+The suggestions are fetched from the configured output endpoint, filtered by the current record's UID. Users can arrow-key through the list to select a ticket, or choose "Enter a Ticket ID manually" for custom input.
+
+If `TicketSuggestionOutput` is not configured or the fetch fails, the CLI falls back to a plain text input prompt.
+
 When the server returns a `repo_mismatch` (Ticket ID belongs to a different repository), the CLI prompts:
 
 ```
@@ -1324,7 +1476,8 @@ Smart behavior:
 - Compares file hashes — unchanged files are skipped
 - Adds project-scoped plugins to `.gitignore` (source of truth is `plugins/claude/` at repo root)
 - Per-plugin scope (project or global) is stored in `.dbo/config.local.json` and remembered for future upgrades
-- On first install of a plugin without a stored preference, prompts for scope
+- On re-install (e.g. after `npm install` or `npm link`), scope is inferred automatically from the global plugin registry (`~/.claude/plugins/installed_plugins.json`) or existing project installation — no prompt is shown
+- On first install with no prior preference and no existing installation, prompts for scope
 - `--global` / `--local` flags override stored preferences and update them
 
 ---
@@ -1508,6 +1661,158 @@ Both `--json` and `--jq` output use syntax highlighting:
 
 ---
 
+## DBO API Parameter Reference
+
+The DBO.io API uses a token architecture for dynamic parameters. All parameters are passed as URL query string key-value pairs.
+
+### Token Syntax
+
+Parameters follow the token delimiter system:
+
+```
+_tokenType@reference$target!defaultValue:modifier=value
+```
+
+| Delimiter | Purpose | Example |
+|-----------|---------|---------|
+| `_` | Prefix for token type | `_filter`, `_sort`, `_limit` |
+| `@` | Reference (column, field, key) | `_filter@FirstName=John` |
+| `$` | Target (scope to a specific output/entity) | `_limit$outputUid=100` |
+| `!` | Default value (fallback) | `_filter@Status!active=value` |
+| `:` | Modifier(s) | `_filter@Name:Contains=john` |
+
+### Output Parameters
+
+These parameters control the output endpoint behavior (`/api/output/{uid}` and `/api/output/entity/{entityUid}`):
+
+#### Filtering
+
+```
+_filter@ColumnName=value                          # exact match (default)
+_filter@ColumnName:Contains=value                 # LIKE %value%
+_filter@ColumnName:StartsWith=value               # LIKE value%
+_filter@ColumnName:EndsWith=value                 # LIKE %value
+_filter@ColumnName:LessThan=value                 # < comparison
+_filter@ColumnName:LessThanOrEqualTo=value        # <= comparison
+_filter@ColumnName:GreaterThan=value              # > comparison
+_filter@ColumnName:GreaterThanOrEqualTo=value     # >= comparison
+_filter@ColumnName:Contains,And=value             # AND logic (default is OR)
+_filter@ColumnName:Contains,Exclude=value         # NOT LIKE
+_filter$outputTarget@ColumnName=value             # scoped to specific output
+```
+
+#### Sorting
+
+```
+_sort=ColumnName                                  # ascending (default)
+_sort=ColumnName:ASC                              # explicit ascending
+_sort=ColumnName:DESC                             # descending
+_sort=Column1:ASC,Column2:DESC                    # multiple sorts (comma-separated)
+_sort=ColumnName ASC                              # space-separated also works
+```
+
+Multiple `_sort` parameters can be specified; earlier sorts take precedence.
+
+#### Pagination
+
+```
+_limit=30                                         # max 30 rows
+_limit=10-30                                      # rows 10 through 30 (range)
+_limit=10&_page=3                                 # 10 rows per page, page 3
+_rowcount=false                                   # disable row count for performance
+```
+
+Deprecated (still accepted): `_maxrows`, `_rows`, `_rowsperpage`
+
+#### Search
+
+```
+_search=keyword                                   # full-text search across searchable columns
+_search@ColumnName=keyword                        # search specific column
+```
+
+#### Template & Format
+
+```
+_template=json_raw                                # format name: json_raw, html, json, json_indented, csv, xml, txt, pdf
+_template=3iX9fHFTL064Shgol8Bktw                 # content UID (custom template)
+_format_values=true                               # enable value formatting in json_raw
+_format=json                                      # legacy format specifier
+_mime=application/json                             # override MIME/content type
+_escape_html=false                                # disable HTML escaping of data values
+```
+
+#### Display Control
+
+```
+_display@tagName=show                             # show a template content tag
+_display@tagName=hide                             # hide a template content tag
+_empty_response_code=404                          # HTTP status when results are empty
+_fallback_content:404=contentUID                  # render a different content on 404
+```
+
+#### Debug & Profiling
+
+```
+_debug=true                                       # general debug output
+_debug:sql=true                                   # return SQL without executing
+_debug:verbose=true                               # verbose debug
+_debug:analysis=true                              # analysis debug
+_profile=true                                     # MiniProfiler output
+```
+
+Other debug sub-keys: `http_modules`, `instance`, `rewrites`, `cache`, `executable_contents`, `security`, `controllers`, `embeds`, `includes`, `contents`, `template_render`, `tokens`, `messages`, `media`, `request_stack`, `query_execution`, `query_building`
+
+#### Control Flags
+
+```
+_strict=true                                      # strict error mode
+_confirm=true                                     # confirmation flag for operations
+_no_transaction=true                              # disable transaction wrapping
+_skip=all                                         # skip execution phases (admin-only)
+_include=value                                    # include token
+_security=value                                   # security filter enforcement
+```
+
+### Data Tokens (used in templates)
+
+| Token | Description |
+|-------|-------------|
+| `#{value@ColumnName}` | Column value from output row |
+| `#{id}` | Row primary key |
+| `#{uid}` | Row UID |
+| `#{CurrentUser@field}` | Current user field (e.g., `FirstName`, `Email`) |
+| `#{request@key}` | URL parameter value |
+| `#{session@variable}` | Session variable |
+| `#{site@field}` | Site field |
+| `#{date:format}` | Current date/time |
+| `#{unique:uid}` | Generate unique UID |
+| `#{count}` | Row count |
+| `#{page}` | Current page number |
+
+### Template Tags
+
+System tags (used in output templates):
+
+| Tag | Purpose |
+|-----|---------|
+| `<#_row>` | Row template |
+| `<#_header>` | Header template |
+| `<#_footer>` | Footer template |
+| `<#_cell>` | Cell template |
+| `<#_empty>` | Empty result template |
+| `<#_noresult>` | No result template |
+| `<#_prompt>` | Prompt template |
+| `<#_shared>` | Shared template |
+| `<#_rowdelimiter>` | Row delimiter |
+| `<#_celldelimiter>` | Cell delimiter |
+| `<#_value>` | Value template |
+| `<#_embed url="...">` | Embed nested content/output |
+
+User-defined tags use `<#reference>` (no underscore prefix).
+
+---
+
 ## Migration from curl
 
 The `dbo` CLI is a drop-in replacement for the curl-based workflow. Here's how common operations translate:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dboio/cli",
-  "version": "0.6.14",
+  "version": "0.8.0",
   "description": "CLI for the DBO.io framework",
   "type": "module",
   "bin": {
@@ -21,8 +21,9 @@
     "test": "node --test src/**/*.test.js tests/**/*.test.js"
   },
   "dependencies": {
-    "commander": "^12.1.0",
     "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "ignore": "^7.0.5",
     "inquirer": "^9.3.0"
   },
   "keywords": [

package/src/commands/add.js

@@ -1,17 +1,15 @@
 import { Command } from 'commander';
-import { readFile, readdir, stat, writeFile } from 'fs/promises';
+import { readFile, readdir, stat, writeFile, mkdir } from 'fs/promises';
 import { join, dirname, basename, extname, relative } from 'path';
 import { DboClient } from '../lib/client.js';
 import { buildInputBody, checkSubmitErrors } from '../lib/input-parser.js';
 import { formatResponse, formatError } from '../lib/formatter.js';
 import { log } from '../lib/logger.js';
 import { shouldSkipColumn } from '../lib/columns.js';
-import { loadAppConfig } from '../lib/config.js';
+import { loadAppConfig, loadExtensionDocumentationMDPlacement, loadDescriptorFilenamePreference } from '../lib/config.js';
 import { checkStoredTicket, clearGlobalTicket } from '../lib/ticketing.js';
 import { checkModifyKey, isModifyKeyError, handleModifyKeyError } from '../lib/modify-key.js';
-
-// Directories and patterns to skip when scanning with `dbo add .`
-const IGNORE_DIRS = new Set(['.dbo', '.git', 'node_modules', '.svn', '.hg']);
+import { loadIgnore } from '../lib/ignore.js';
 
 export const addCommand = new Command('add')
   .description('Add a new file to DBO.io (creates record on server)')
@@ -57,6 +55,23 @@ export const addCommand = new Command('add')
  * Add a single file to DBO.io.
  * Returns the defaults used (entity, contentColumn) for batch reuse.
  */
+/**
+ * Detect whether a file lives in the project-root Documentation/ directory
+ * AND the ExtensionDocumentationMDPlacement preference is 'root'.
+ * Returns detection info object or null if not applicable.
+ *
+ * @param {string} filePath - Path to the file being added
+ */
+async function detectDocumentationFile(filePath) {
+  const placement = await loadExtensionDocumentationMDPlacement();
+  if (placement !== 'root') return null;
+
+  const rel = relative(process.cwd(), filePath).replace(/\\/g, '/');
+  if (!rel.startsWith('Documentation/')) return null;
+
+  return { entity: 'extension', descriptor: 'documentation' };
+}
+
 async function addSingleFile(filePath, client, options, batchDefaults) {
   const dir = dirname(filePath);
   const ext = extname(filePath);
@@ -87,6 +102,33 @@ async function addSingleFile(filePath, client, options, batchDefaults) {
     return await submitAdd(meta, metaPath, filePath, client, options);
   }
 
+  // Step 3b: Auto-infer entity/descriptor for Documentation/ files when root placement is configured
+  const docInfo = await detectDocumentationFile(filePath);
+  if (docInfo) {
+    const filenameCol = await loadDescriptorFilenamePreference('documentation') || 'Name';
+    const docBase = basename(filePath, extname(filePath));
+    const companionDir = join(process.cwd(), 'Extensions', 'Documentation');
+    await mkdir(companionDir, { recursive: true });
+
+    const docMeta = {
+      _entity: 'extension',
+      Descriptor: 'documentation',
+      [filenameCol]: docBase,
+      Name: docBase,
+    };
+
+    // Find the content column name from saved preferences
+    const contentCol = filenameCol === 'Name' ? 'String10' : 'String10';
+    const relPath = relative(process.cwd(), filePath).replace(/\\/g, '/');
+    docMeta[contentCol] = `@/${relPath}`;
+    docMeta._contentColumns = [contentCol];
+
+    const docMetaFile = join(companionDir, `${docBase}.metadata.json`);
+    await writeFile(docMetaFile, JSON.stringify(docMeta, null, 2) + '\n');
+    log.success(`Created companion metadata at ${docMetaFile}`);
+    return await submitAdd(docMeta, docMetaFile, filePath, client, options);
+  }
+
   // Step 4: No usable metadata — interactive wizard
   const inquirer = (await import('inquirer')).default;
 
@@ -379,23 +421,26 @@ async function addDirectory(dirPath, client, options) {
  *   - It has no companion .metadata.json, OR
  *   - Its .metadata.json exists but has no _CreatedOn (never been on server)
  */
-async function findUnaddedFiles(dir) {
+async function findUnaddedFiles(dir, ig) {
+  if (!ig) ig = await loadIgnore();
+
   const results = [];
   const entries = await readdir(dir, { withFileTypes: true });
 
   for (const entry of entries) {
     const fullPath = join(dir, entry.name);
+    const relPath = relative(process.cwd(), fullPath).replace(/\\/g, '/');
 
     if (entry.isDirectory()) {
-      if (IGNORE_DIRS.has(entry.name) || entry.name.startsWith('.')) continue;
-      results.push(...await findUnaddedFiles(fullPath));
+      if (ig.ignores(relPath + '/') || ig.ignores(relPath)) continue;
+      results.push(...await findUnaddedFiles(fullPath, ig));
       continue;
     }
 
-    // Skip metadata files themselves
+    // Skip metadata files themselves (structural, not user-configurable)
     if (entry.name.endsWith('.metadata.json')) continue;
-    // Skip dotfiles
-    if (entry.name.startsWith('.')) continue;
+    // Skip ignored files
+    if (ig.ignores(relPath)) continue;
 
     // Check for companion metadata
     const ext = extname(entry.name);