iranti 0.1.4 → 0.2.0

package/README.md

@@ -70,6 +70,34 @@ Validated with multiple agent frameworks:
 
 Full validation report: [`docs/internal/validation_results.md`](docs/internal/validation_results.md) | Multi-framework details: [`docs/internal/MULTI_FRAMEWORK_VALIDATION.md`](docs/internal/MULTI_FRAMEWORK_VALIDATION.md)
 
+### Conflict Benchmark Baseline
+
+Iranti now also has an adversarial conflict benchmark that measures contradiction handling rather than basic retrieval.
+
+| Suite | Score | Notes |
+|---|---|---|
+| **Direct contradiction** | `4/4` | Same entity+key conflicts are explicitly resolved or escalated |
+| **Temporal conflict** | `3/4` | One known-failing edge remains |
+| **Cascading conflict** | `0/4` | Cross-key contradiction detection not implemented yet |
+| **Multi-hop conflict** | `0/4` | Graph-aware conflict reasoning not implemented yet |
+| **Total** | `7/16 (44%)` | Honest baseline for the current Librarian |
+
+Conflict benchmark methodology: [`docs/internal/conflict_benchmark.md`](docs/internal/conflict_benchmark.md)
+
+### Consistency Validation
+
+Iranti also now documents and validates its consistency model empirically:
+
+| Check | Result |
+|---|---|
+| Concurrent write serialization | `PASS` |
+| Read-after-write visibility | `PASS` |
+| Escalation state integrity | `PASS` |
+| Observe isolation from uncommitted writes | `PASS` |
+| **Total** | `4/4` |
+
+Consistency model and validation: [`docs/internal/consistency_model.md`](docs/internal/consistency_model.md)
+
 ### Goal 1: Easy Integration
 
 - **Entity**: `project/quantum_bridge`
@@ -108,9 +136,93 @@ Full validation report: [`docs/internal/validation_results.md`](docs/internal/va
 
 Full validation report: [`docs/internal/validation_results.md`](docs/internal/validation_results.md)
 
+## Gap Analysis
+
+Iranti targets a specific gap in the agent infrastructure stack: most competing systems give you semantic retrieval, framework-specific memory, or raw vector storage, but not the same combination of structured fact storage, cross-agent sharing, identity-based lookup, explicit confidence, and developer-visible conflict handling in one self-hostable package.
+
+The current competitive case for Iranti is strongest when a team needs memory that behaves more like shared infrastructure than a chat transcript: facts are attached to entities, retrieved deterministically by `entityType/entityId + key`, versioned over time, and made available across agents without framework lock-in.
+
+### Where Iranti Is Differentiated
+
+- Identity-first fact retrieval through `entityType/entityId + key`
+- Cross-agent fact sharing as a first-class model
+- Conflict-aware writes through the Librarian
+- Explicit per-fact confidence scores
+- Per-agent memory injection through the Attendant
+- Temporal exact lookup with `asOf` and ordered `history()`
+- Relationship primitives through `relate()`, `getRelated()`, and `getRelatedDeep()`
+- Hybrid retrieval when exact keys are unknown
+- Local install + project binding flow for Claude Code and Codex
+- Published npm / PyPI surfaces with machine-level CLI setup
+
+### Why That Gap Exists
+
+The current landscape splits into three buckets:
+
+1. **Memory libraries**
+   - Systems like Mem0, Zep, Letta, and framework-native memory layers solve parts of the problem.
+   - They usually optimize for semantic retrieval, agent-local memory, or framework integration.
+   - They rarely expose deterministic `entity + key` lookup, explicit confidence surfaces, and developer-controlled conflict handling together.
+
+2. **Vector databases**
+   - Pinecone, Weaviate, Qdrant, Chroma, Milvus, LanceDB, and `pgvector` solve storage and retrieval infrastructure.
+   - They do not, by themselves, solve memory semantics such as conflict resolution, context injection, fact lifecycle, or shared agent-facing state.
+
+3. **Multi-agent frameworks**
+   - CrewAI, LangGraph, AutoGen, CAMEL, MetaGPT, and similar frameworks often include some memory support.
+   - In practice, that memory is usually framework-coupled, shallow on conflict semantics, and difficult to reuse outside the framework that created it.
+
+### Main Gaps
+
+1. **Operational maturity**
+   - Local PostgreSQL setup is still a real source of friction.
+   - The product needs stronger diagnostics, connection recovery, and less dependence on users debugging local database state by hand.
+
+2. **Onboarding still has sharp edges**
+   - `iranti setup` is materially better than before, but first-run still assumes too much infrastructure literacy.
+   - Managed Postgres paths, cleaner bootstrap verification, and fewer environment-level surprises are still needed.
+
+3. **No operator UI yet**
+   - Iranti is still CLI-first.
+   - There is no control plane yet for provider keys, project bindings, integrations, memory inspection, and escalation review.
+
+4. **Adoption proof is still early**
+   - The repo has validation experiments and real local end-to-end usage, but broad production adoption is still limited.
+   - The next product truth has to come from external users and real workloads, not more speculative architecture alone.
+
+5. **Hosted product is not built**
+   - Open-source/local infrastructure is the active surface today.
+   - Hosted deployment, multi-tenant operations, billing, and cloud onboarding remain future work.
+
+6. **Graph-native reasoning is still limited**
+   - Iranti supports explicit entity relationships today.
+   - It does not yet compete with graph-first systems on temporal graph traversal or graph-native reasoning depth.
+
+7. **Memory extraction is not the main model**
+   - Iranti supports structured writes and ingest/chunking, but it is not primarily a "dump arbitrary conversations in and auto-magically derive perfect memory" system.
+   - That is a deliberate tradeoff in favor of explicit, inspectable facts, but it increases integration work.
+
+### Current Position
+
+Iranti is strongest today as infrastructure for developers building multi-agent systems who need shared, structured, queryable memory rather than pure semantic recall. The current evidence base is now more concrete than a positioning claim alone:
+
+- `16/16` fictional-fact transfer in retrieval validation
+- `7/16 (44%)` on an adversarial conflict benchmark
+- `4/4` on empirical consistency validation for serialized writes and read visibility
+
+That is not a claim that multi-agent memory is solved. It is a claim that Iranti now has reproducible evidence for three things at once:
+
+- exact cross-agent fact transfer works
+- same-key conflicting writes are serialized and observable
+- conflict handling quality is measurable, including clearly documented failure modes
+
+The next leverage is still product simplicity: setup, operations, and day-to-day inspection need to be simple enough that real users keep Iranti in the loop.
+
 ## Quickstart
 
-**Requirements**: Node.js 18+, Docker, Python 3.8+
+**Requirements**: Node.js 18+, PostgreSQL, Python 3.8+
+
+Docker is optional. It is one local way to run PostgreSQL if you do not already have a database.
 
 ```bash
 # 1. Clone and configure
@@ -136,6 +248,9 @@ npm run api                   # Runs on port 3001
 
 # 5. Install Python client
 pip install iranti
+
+# Optional: install the TypeScript client
+npm install @iranti/sdk
 ```
 
 ### Archivist Scheduling Knobs
@@ -233,7 +348,11 @@ iranti install --scope user
 `iranti setup` is the recommended first-run path. It walks through:
 - shared vs isolated runtime setup
 - instance creation or update
-- database URL entry
+- API port selection with conflict detection and next-free suggestions
+- database onboarding:
+  - existing Postgres
+  - managed Postgres
+  - optional Docker-hosted Postgres for local development
 - provider API keys
 - Iranti client API key generation
 - one or more project bindings
@@ -242,8 +361,11 @@ iranti install --scope user
 For automation:
 - `iranti setup --defaults` uses sensible defaults plus environment/flag input, but still requires a real `DATABASE_URL`.
 - `iranti setup --config <file>` reads a JSON setup plan for repeatable bootstrap.
+- `--bootstrap-db` runs migrations and seeding during automated setup when the database is reachable.
 - Example config: [docs/guides/iranti.setup.example.json](docs/guides/iranti.setup.example.json)
 
+Default API port remains `3001`. The setup wizard now warns when that port is already in use and suggests the next free port instead of forcing users to debug the collision manually.
+
 Defaults:
 - Windows user scope: `%USERPROFILE%\\.iranti`
 - Windows system scope: `%ProgramData%\\Iranti`
@@ -367,6 +489,51 @@ for fact in facts:
     print(f"[{fact['key']}] {fact['summary']} (confidence: {fact['confidence']})")
 ```
 
+### Graph Traversal
+
+```python
+from clients.python.iranti import IrantiClient
+
+client = IrantiClient(base_url="http://localhost:3001", api_key="your_api_key_here")
+
+# Agent 1 writes facts and links them into a graph.
+client.write("researcher/jane_smith", "affiliation", {"lab": "CSAIL"}, "Jane Smith is affiliated with CSAIL", 90, "OpenAlex", "research_agent")
+client.write("project/quantum_bridge", "status", {"phase": "active"}, "Quantum Bridge is active", 88, "project_brief", "research_agent")
+
+client.relate("researcher/jane_smith", "MEMBER_OF", "lab/csail", created_by="research_agent")
+client.relate("lab/csail", "LEADS", "project/quantum_bridge", created_by="research_agent")
+
+# Agent 2 starts cold and traverses outward from Jane Smith.
+one_hop = client.related("researcher/jane_smith")
+labs = [f"{r['toType']}/{r['toId']}" for r in one_hop if r["relationshipType"] == "MEMBER_OF"]
+
+projects = []
+for lab in labs:
+    for rel in client.related(lab):
+        if rel["relationshipType"] == "LEADS":
+            project = f"{rel['toType']}/{rel['toId']}"
+            status = client.query(project, "status")
+            projects.append((project, status.value["phase"]))
+
+print(projects)
+# Agent 2 learned which project Jane Smith is connected to without being told the project directly.
+```
+
+### Relationship Types
+
+Relationship types are caller-defined strings. Common conventions:
+
+| Relationship Type | Meaning |
+|---|---|
+| `MEMBER_OF` | Entity belongs to a team, lab, org, or group |
+| `PART_OF` | Entity is a component or sub-unit of another entity |
+| `AUTHORED` | Person or agent created a document, paper, or artifact |
+| `LEADS` | Person, team, or org leads a project or effort |
+| `DEPENDS_ON` | Project, service, or task depends on another entity |
+| `REPORTS_TO` | Directed reporting relationship between people or agents |
+
+Use uppercase snake case for consistency. Iranti does not enforce a fixed ontology here; the calling application owns the relationship vocabulary.
+
 ### Hybrid Search
 
 ```python
@@ -519,7 +686,7 @@ Iranti has four internal components:
 
 | Component | Role |
 |---|---|
-| **Library** | PostgreSQL knowledge base. Active truth in `knowledge_base` with full provenance in `archive`; archived rows are retained and marked `[ARCHIVED]` in active storage. |
+| **Library** | PostgreSQL knowledge base. Current truth lives in `knowledge_base`; closed and contested intervals live in `archive`. |
 | **Librarian** | Manages all writes. Detects conflicts, reasons about resolution, escalates when uncertain. |
 | **Attendant** | Per-agent working memory manager. Implements `attend()`, `observe()`, and `handshake()` APIs. |
 | **Archivist** | Periodic cleanup. Archives expired and low-confidence entries. Processes human-resolved conflicts. |
@@ -529,7 +696,7 @@ Iranti has four internal components:
 Express server on port 3001 with endpoints:
 
 - `POST /kb/write` - Write atomic fact
-- `POST /kb/ingest` - Ingest raw text, auto-chunk into facts
+- `POST /kb/ingest` - Ingest raw text for one entity, auto-chunk into facts with per-fact confidence and per-fact write outcomes
 - `GET /kb/query/:entityType/:entityId/:key` - Query specific fact
 - `GET /kb/query/:entityType/:entityId` - Query all facts for entity
 - `GET /kb/search` - Hybrid search across facts
@@ -549,8 +716,8 @@ All endpoints require `X-Iranti-Key` header for authentication.
 Six PostgreSQL tables:
 
 ```
-knowledge_base          - active truth (archived rows retained with confidence=0)
-archive                 - full provenance history, never deleted
+knowledge_base          - current truth (one live row per entity/key)
+archive                 - temporal and provenance history for superseded, contradicted, escalated, and expired rows
 entity_relationships    - directional graph: MEMBER_OF, PART_OF, AUTHORED, etc.
 entities                - canonical entity identity registry
 entity_aliases          - normalized aliases mapped to canonical entities
@@ -559,7 +726,7 @@ write_receipts          - idempotency receipts for requestId replay safety
 
 New entity types, relationship types, and fact keys do not require migrations; they are caller-defined strings.
 
-**Archive semantics**: When an entry is archived, it remains in knowledge_base with confidence set to 0 and summary marked as `[ARCHIVED]`. A full copy is written to the archive table for traceability. Nothing is ever truly deleted.
+**Archive semantics**: When a current fact is superseded or contested, the current row is removed from `knowledge_base` and a closed historical interval is written to `archive`. Temporal queries use `validFrom` / `validUntil` plus archive metadata to answer point-in-time reads.
 
 ---
 

package/dist/scripts/iranti-cli.js

@@ -11,6 +11,7 @@ const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
 const promises_2 = __importDefault(require("readline/promises"));
 const stream_1 = require("stream");
+const net_1 = __importDefault(require("net"));
 const client_1 = require("../src/library/client");
 const apiKeys_1 = require("../src/security/apiKeys");
 const PROVIDER_ENV_KEYS = {
@@ -135,29 +136,43 @@ function resolveInstallRoot(args, scope) {
     return userRoot;
 }
 function getPackageVersion() {
+    const pkgPath = path_1.default.join(packageRoot(), 'package.json');
+    if (fs_1.default.existsSync(pkgPath)) {
+        try {
+            const raw = fs_1.default.readFileSync(pkgPath, 'utf-8');
+            const pkg = JSON.parse(raw);
+            return String(pkg.version ?? '0.0.0');
+        }
+        catch {
+            return '0.0.0';
+        }
+    }
+    return '0.0.0';
+}
+function packageRoot() {
     let dir = __dirname;
-    for (let i = 0; i < 5; i++) {
+    for (let i = 0; i < 6; i++) {
         const pkgPath = path_1.default.join(dir, 'package.json');
         if (fs_1.default.existsSync(pkgPath)) {
-            try {
-                const raw = fs_1.default.readFileSync(pkgPath, 'utf-8');
-                const pkg = JSON.parse(raw);
-                return String(pkg.version ?? '0.0.0');
-            }
-            catch {
-                return '0.0.0';
-            }
+            return dir;
         }
         const parent = path_1.default.dirname(dir);
         if (parent === dir)
             break;
         dir = parent;
     }
-    return '0.0.0';
+    return process.cwd();
 }
 function builtScriptPath(scriptName) {
     return path_1.default.resolve(__dirname, `${scriptName}.js`);
 }
+function formatSetupBootstrapFailure(error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return new Error(`Database bootstrap failed after instance configuration. ` +
+        `Common causes are a non-empty database that Prisma has not baselined yet, or a PostgreSQL server without the pgvector extension installed. ` +
+        `Re-run setup without --bootstrap-db, or point Iranti at a fresh pgvector-capable database. ` +
+        `Underlying error: ${reason}`);
+}
 async function handoffToScript(scriptName, rawArgs) {
     const builtPath = builtScriptPath(scriptName);
     if (fs_1.default.existsSync(builtPath)) {
@@ -203,6 +218,34 @@ async function handoffToScript(scriptName, rawArgs) {
         });
     });
 }
+async function runBundledScript(scriptName, rawArgs, extraEnv) {
+    const builtPath = builtScriptPath(scriptName);
+    if (!fs_1.default.existsSync(builtPath)) {
+        throw new Error(`Unable to locate bundled script: ${scriptName}`);
+    }
+    await new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)(process.execPath, [builtPath, ...rawArgs], {
+            stdio: 'inherit',
+            env: {
+                ...process.env,
+                ...extraEnv,
+            },
+            cwd: packageRoot(),
+        });
+        child.on('error', reject);
+        child.on('exit', (code, signal) => {
+            if (signal) {
+                reject(new Error(`${scriptName} terminated with signal ${signal}`));
+                return;
+            }
+            if ((code ?? 0) !== 0) {
+                reject(new Error(`${scriptName} exited with code ${code ?? 1}`));
+                return;
+            }
+            resolve();
+        });
+    });
+}
 async function ensureDir(dir) {
     await promises_1.default.mkdir(dir, { recursive: true });
 }
@@ -634,6 +677,117 @@ function hasCodexInstalled() {
         return false;
     }
 }
+function hasDockerInstalled() {
+    try {
+        const proc = process.platform === 'win32'
+            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', 'docker --version'], { stdio: 'ignore' })
+            : (0, child_process_1.spawnSync)('docker', ['--version'], { stdio: 'ignore' });
+        return proc.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function isPortAvailable(port, host = '127.0.0.1') {
+    return await new Promise((resolve) => {
+        const server = net_1.default.createServer();
+        server.unref();
+        server.on('error', () => resolve(false));
+        server.listen(port, host, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+async function findNextAvailablePort(start, host = '127.0.0.1', maxSteps = 50) {
+    for (let port = start; port < start + maxSteps; port += 1) {
+        if (await isPortAvailable(port, host)) {
+            return port;
+        }
+    }
+    throw new Error(`No available port found in range ${start}-${start + maxSteps - 1}.`);
+}
+async function chooseAvailablePort(session, promptText, preferredPort, allowOccupiedCurrent = false) {
+    let suggested = preferredPort;
+    if (!allowOccupiedCurrent && !(await isPortAvailable(preferredPort))) {
+        suggested = await findNextAvailablePort(preferredPort + 1);
+        console.log(`${warnLabel()} Port ${preferredPort} is already in use. Suggested port: ${suggested}`);
+    }
+    while (true) {
+        const raw = await promptNonEmpty(session, promptText, String(suggested));
+        const parsed = Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            console.log(`${warnLabel()} Port must be a positive integer.`);
+            continue;
+        }
+        if (allowOccupiedCurrent && parsed === preferredPort) {
+            return parsed;
+        }
+        if (await isPortAvailable(parsed)) {
+            return parsed;
+        }
+        const next = await findNextAvailablePort(parsed + 1);
+        console.log(`${warnLabel()} Port ${parsed} is already in use. Try ${next} instead.`);
+        suggested = next;
+    }
+}
+async function waitForTcpPort(host, port, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const ready = await new Promise((resolve) => {
+            const socket = net_1.default.connect({ host, port });
+            socket.once('connect', () => {
+                socket.destroy();
+                resolve(true);
+            });
+            socket.once('error', () => {
+                socket.destroy();
+                resolve(false);
+            });
+        });
+        if (ready)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+    }
+    throw new Error(`Timed out waiting for ${host}:${port} to accept TCP connections.`);
+}
+async function runDockerPostgresContainer(options) {
+    const inspect = process.platform === 'win32'
+        ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', `docker ps -a --format "{{.Names}}"`], { encoding: 'utf8' })
+        : (0, child_process_1.spawnSync)('docker', ['ps', '-a', '--format', '{{.Names}}'], { encoding: 'utf8' });
+    const names = (inspect.stdout ?? '').split(/\r?\n/).map((value) => value.trim()).filter(Boolean);
+    if (names.includes(options.containerName)) {
+        const start = process.platform === 'win32'
+            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', `docker start ${options.containerName}`], { stdio: 'inherit' })
+            : (0, child_process_1.spawnSync)('docker', ['start', options.containerName], { stdio: 'inherit' });
+        if (start.status !== 0) {
+            throw new Error(`Failed to start existing Docker container '${options.containerName}'.`);
+        }
+    }
+    else {
+        const args = [
+            'run',
+            '-d',
+            '--name',
+            options.containerName,
+            '-e',
+            `POSTGRES_USER=postgres`,
+            '-e',
+            `POSTGRES_PASSWORD=${options.password}`,
+            '-e',
+            `POSTGRES_DB=${options.database}`,
+            '-p',
+            `${options.hostPort}:5432`,
+            'pgvector/pgvector:pg16',
+        ];
+        const result = process.platform === 'win32'
+            ? (0, child_process_1.spawnSync)(process.env.ComSpec ?? 'cmd.exe', ['/d', '/c', ['docker', ...args].join(' ')], { stdio: 'inherit' })
+            : (0, child_process_1.spawnSync)('docker', args, { stdio: 'inherit' });
+        if (result.status !== 0) {
+            throw new Error(`Failed to start Docker PostgreSQL container '${options.containerName}'.`);
+        }
+    }
+    await waitForTcpPort('127.0.0.1', options.hostPort, 30000);
+}
 async function executeSetupPlan(plan) {
     await ensureRuntimeInstalled(plan.root, plan.scope);
     const configured = await ensureInstanceConfigured(plan.root, plan.instanceName, {
@@ -643,6 +797,17 @@ async function executeSetupPlan(plan) {
         providerKeys: plan.providerKeys,
         apiKey: plan.apiKey,
     });
+    if (plan.bootstrapDatabase) {
+        try {
+            await runBundledScript('setup', [], {
+                DATABASE_URL: plan.databaseUrl,
+                IRANTI_ESCALATION_DIR: path_1.default.join(configured.instanceDir, 'escalation'),
+            });
+        }
+        catch (error) {
+            throw formatSetupBootstrapFailure(error);
+        }
+    }
     const bindings = [];
     for (const project of plan.projects) {
         const projectPath = path_1.default.resolve(project.path);
@@ -737,6 +902,7 @@ function parseSetupConfig(filePath) {
         projects,
         codex: Boolean(raw?.codex),
         codexAgent: raw?.codexAgent ? sanitizeIdentifier(String(raw.codexAgent), 'codex_code') : undefined,
+        bootstrapDatabase: Boolean(raw?.bootstrapDatabase),
     };
 }
 function defaultsSetupPlan(args) {
@@ -791,6 +957,7 @@ function defaultsSetupPlan(args) {
         projects,
         codex: hasFlag(args, 'codex'),
         codexAgent: sanitizeIdentifier(getFlag(args, 'codex-agent') ?? 'codex_code', 'codex_code'),
+        bootstrapDatabase: hasFlag(args, 'bootstrap-db'),
     };
 }
 function detectProviderKey(provider, env) {
@@ -1054,22 +1221,51 @@ async function setupCommand(args) {
         else {
             console.log(`${infoLabel()} Creating new instance '${instanceName}'.`);
         }
-        let port = 3001;
+        const existingPort = Number.parseInt(existingInstance?.env.IRANTI_PORT ?? '3001', 10);
+        const port = await chooseAvailablePort(prompt, 'Iranti API port', existingPort, Boolean(existingInstance));
+        const dockerAvailable = hasDockerInstalled();
+        let dbUrl = '';
+        let bootstrapDatabase = false;
         while (true) {
-            const raw = await promptNonEmpty(prompt, 'Port', existingInstance?.env.IRANTI_PORT ?? '3001');
-            const parsed = Number.parseInt(raw, 10);
-            if (Number.isFinite(parsed) && parsed > 0) {
-                port = parsed;
+            const defaultMode = dockerAvailable ? 'docker' : 'existing';
+            const dbMode = (await prompt.line('Database setup mode: existing, managed, or docker', defaultMode) ?? defaultMode).trim().toLowerCase();
+            if (dbMode === 'existing' || dbMode === 'managed') {
+                while (true) {
+                    dbUrl = await promptNonEmpty(prompt, 'DATABASE_URL', existingInstance?.env.DATABASE_URL ?? `postgresql://postgres:yourpassword@localhost:5432/iranti_${instanceName}`);
+                    if (!detectPlaceholder(dbUrl))
+                        break;
+                    console.log(`${warnLabel()} DATABASE_URL still looks like a placeholder. Enter a real connection string before finishing setup.`);
+                }
+                bootstrapDatabase = await promptYesNo(prompt, 'Run migrations and seed the database now?', true);
                 break;
             }
-            console.log(`${warnLabel()} Port must be a positive integer.`);
-        }
-        let dbUrl = '';
-        while (true) {
-            dbUrl = await promptNonEmpty(prompt, 'DATABASE_URL', existingInstance?.env.DATABASE_URL ?? `postgresql://postgres:yourpassword@localhost:5432/iranti_${instanceName}`);
-            if (!detectPlaceholder(dbUrl))
+            if (dbMode === 'docker') {
+                if (!dockerAvailable) {
+                    console.log(`${warnLabel()} Docker is not installed or not on PATH. Choose existing or managed instead.`);
+                    continue;
+                }
+                const dbHostPort = await chooseAvailablePort(prompt, 'Docker PostgreSQL host port', 5432, false);
+                const dbName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker PostgreSQL database name', `iranti_${instanceName}`), `iranti_${instanceName}`);
+                const dbPassword = await promptRequiredSecret(prompt, 'Docker PostgreSQL password');
+                const containerName = sanitizeIdentifier(await promptNonEmpty(prompt, 'Docker container name', `iranti_${instanceName}_db`), `iranti_${instanceName}_db`);
+                dbUrl = `postgresql://postgres:${dbPassword}@localhost:${dbHostPort}/${dbName}`;
+                console.log(`${infoLabel()} Docker will be used only for PostgreSQL. Iranti itself does not require Docker once a PostgreSQL database is available.`);
+                if (await promptYesNo(prompt, `Start or reuse Docker container '${containerName}' now?`, true)) {
+                    await runDockerPostgresContainer({
+                        containerName,
+                        hostPort: dbHostPort,
+                        password: dbPassword,
+                        database: dbName,
+                    });
+                    console.log(`${okLabel()} Docker PostgreSQL ready at localhost:${dbHostPort}`);
+                    bootstrapDatabase = true;
+                }
+                else {
+                    bootstrapDatabase = await promptYesNo(prompt, 'Will you start PostgreSQL separately before first run?', false);
+                }
                 break;
-            console.log(`${warnLabel()} DATABASE_URL still looks like a placeholder. Enter a real connection string before finishing setup.`);
+            }
+            console.log(`${warnLabel()} Choose one of: existing, managed, docker.`);
         }
         let provider = normalizeProvider(existingInstance?.env.LLM_PROVIDER ?? 'openai') ?? 'openai';
         while (true) {
@@ -1160,6 +1356,7 @@ async function setupCommand(args) {
             projects,
             codex,
             codexAgent: projects[0]?.agentId,
+            bootstrapDatabase,
         });
     });
     if (!result) {
@@ -1874,7 +2071,7 @@ function printHelp() {
 
 Machine-level:
   iranti install [--scope user|system] [--root <path>]
-  iranti setup [--scope user|system] [--root <path>] [--config <file> | --defaults]
+  iranti setup [--scope user|system] [--root <path>] [--config <file> | --defaults] [--db-url <url>] [--bootstrap-db]
 
 Instance-level:
   iranti instance create <name> [--port 3001] [--db-url <url>] [--api-key <token>] [--provider <name>] [--provider-key <token>] [--scope user|system]