people-truth 1.0.0 → 1.1.3

package/.env.example

@@ -0,0 +1,7 @@
+PEOPLE_TRUTH_PROVIDER="sqlite"
+PEOPLE_TRUTH_SQLITE_PATH="$HOME/.people-truth/people-truth.sqlite"
+
+# For Supabase:
+# PEOPLE_TRUTH_PROVIDER="supabase"
+# SUPABASE_URL="https://your-project-ref.supabase.co"
+# SUPABASE_KEY="your-service-role-or-secret-key"

package/README.md

@@ -1,6 +1,11 @@
 # people-truth
 
-`people-truth` is a Supabase/Postgres-backed source of truth for stable person identities, names, mentions, affiliations, identifiers, and sourced facts.
+`people-truth` is a portable source of truth for stable person identities, names, mentions, affiliations, identifiers, and sourced facts.
+
+It can run in two modes:
+
+- SQLite: local-first, no cloud dependency, good for personal agents and laptops.
+- Supabase/Postgres: hosted and shareable, good for multi-device or team use.
 
 Supabase is treated as a replaceable Postgres runtime. The durable contract is the SQL migration plus the CLI behavior.
 
@@ -15,43 +20,79 @@ For local development:
 
 ```bash
 npm install
+npm test
 npm run build
-npm run dev -- --help
 ```
 
-## Configure
+## Quick Start: SQLite
 
-Create a local `.env` file:
+SQLite is the default provider. This creates `.env`, initializes the local database, and verifies the schema:
 
 ```bash
-ptruth init --url "https://your-project-ref.supabase.co" --key "your-service-role-or-secret-key"
-ptruth status
+ptruth setup --provider sqlite
+ptruth db status
 ```
 
-The CLI reads `SUPABASE_URL` and `SUPABASE_KEY` from `.env`, or from `~/.codex/.env` when present.
+By default, the database lives at:
 
-## Database
+```text
+~/.people-truth/people-truth.sqlite
+```
+
+Use a custom path when needed:
+
+```bash
+ptruth setup --provider sqlite --sqlite-path ./people.sqlite --force
+```
+
+## Quick Start: Supabase
+
+Create a Supabase project, then configure credentials:
+
+```bash
+ptruth setup \
+  --provider supabase \
+  --url "https://your-project-ref.supabase.co" \
+  --key "your-service-role-or-secret-key"
+```
 
-Apply migrations to a linked Supabase project:
+Check whether the required tables exist:
+
+```bash
+ptruth db status
+```
+
+If tables are missing, print the SQL and run it in the Supabase SQL editor:
+
+```bash
+ptruth db schema --provider supabase
+```
+
+From this repository, you can also link a Supabase project and push migrations:
 
 ```bash
 npx supabase link --project-ref your-project-ref
 npm run db:push
 ```
 
-The main files are:
+## Configuration
 
-- `supabase/migrations/20260611000000_initial_people_truth.sql`
-- `supabase/schema.sql`
+The CLI reads `.env` first, then `~/.codex/.env` when present.
 
-The schema centers on:
+SQLite:
 
-- `people`: stable UUID identity.
-- `person_names`: canonical names, aliases, pen names, former names, foreign names.
-- `person_identifiers`: external IDs and URLs.
-- `person_affiliations`: organization and role history.
-- `person_facts`: sourced predicate/value facts.
-- `sources`: provenance.
+```env
+PEOPLE_TRUTH_PROVIDER="sqlite"
+PEOPLE_TRUTH_SQLITE_PATH="$HOME/.people-truth/people-truth.sqlite"
+```
+
+Supabase:
+
+```env
+PEOPLE_TRUTH_PROVIDER="supabase"
+SUPABASE_URL="https://your-project-ref.supabase.co"
+SUPABASE_KEY="your-service-role-or-secret-key"
+```
 
 ## CLI
 
@@ -70,6 +111,28 @@ All commands support JSON output:
 ptruth people show "梁启超" -o json
 ```
 
+## Database
+
+The schema centers on:
+
+- `people`: stable UUID identity.
+- `person_names`: canonical names, aliases, pen names, former names, foreign names.
+- `person_identifiers`: external IDs and URLs.
+- `person_affiliations`: organization and role history.
+- `person_facts`: sourced predicate/value facts.
+- `sources`: provenance.
+
+Package SQL assets:
+
+- `supabase/migrations/20260611000000_initial_people_truth.sql`
+- `supabase/schema.sql`
+
+For SQLite, the equivalent schema is embedded in the CLI and can be printed:
+
+```bash
+ptruth db schema --provider sqlite
+```
+
 ## Mentions
 
 Use Markdown-compatible person mentions:
@@ -90,4 +153,4 @@ fix: handle duplicate person names
 feat!: change mention format
 ```
 
-CI runs typecheck/build/pack. Release publishes to npm when `NPM_TOKEN` is configured in GitHub repository secrets.
+CI runs typecheck/tests/build/pack. Release publishes to npm when `NPM_TOKEN` is configured in GitHub repository secrets.

package/dist/cli.js

@@ -1,33 +1,80 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { existsSync, writeFileSync } from "node:fs";
-import { resolve } from "node:path";
 import { addFact, listFacts } from "./facts.js";
-import { getConfig } from "./config.js";
+import { defaultSqlitePath, readConfig } from "./config.js";
 import { addPerson, formatPersonMention, getPerson, searchPeople } from "./people.js";
 import { printResult } from "./output.js";
+import { checkDatabase, schemaFor, setupDatabase, writeEnvFile } from "./setup.js";
 const program = new Command();
 program
     .name("people-truth")
-    .description("Supabase-backed personal source of truth for people.")
+    .description("Portable source of truth for people, backed by SQLite or Supabase.")
     .option("-o, --output <mode>", "Output mode: table or json", "table");
 program
-    .command("init")
-    .description("Create a local .env file for Supabase credentials")
-    .requiredOption("--url <url>", "Supabase project URL")
-    .requiredOption("--key <key>", "Supabase service-role or secret key")
+    .command("setup")
+    .description("Configure people-truth and initialize the selected database")
+    .option("--provider <provider>", "sqlite or supabase", "sqlite")
+    .option("--url <url>", "Supabase project URL")
+    .option("--key <key>", "Supabase service-role or secret key")
+    .option("--sqlite-path <path>", "SQLite database path", defaultSqlitePath)
     .option("--path <path>", "Env file path", ".env")
     .option("--force", "Overwrite an existing env file", false)
+    .option("--skip-db", "Write config without initializing/checking database", false)
     .action(async (options) => {
     await run(async () => {
-        const envPath = resolve(options.path);
-        if (existsSync(envPath) && !options.force) {
-            throw new Error(`${envPath} already exists. Re-run with --force to overwrite it.`);
+        const provider = parseProvider(options.provider);
+        const envPath = writeEnvFile({
+            provider,
+            path: options.path,
+            force: options.force,
+            supabaseUrl: options.url,
+            supabaseKey: options.key,
+            sqlitePath: options.sqlitePath
+        });
+        const result = {
+            ok: true,
+            provider,
+            envPath
+        };
+        if (provider === "sqlite")
+            result.sqlitePath = options.sqlitePath;
+        if (!options.skipDb) {
+            if (provider === "sqlite") {
+                result.database = await setupDatabase({ provider, sqlitePath: options.sqlitePath });
+            }
+            else {
+                result.database = await checkDatabase({
+                    provider,
+                    supabaseUrl: options.url,
+                    supabaseKey: options.key
+                });
+                result.nextStep = "If tables are missing, run `ptruth db schema --provider supabase` and apply the SQL in Supabase.";
+            }
         }
-        writeFileSync(envPath, `SUPABASE_URL="${options.url}"\nSUPABASE_KEY="${options.key}"\n`, {
-            mode: 0o600
+        printResult(result, outputMode());
+    });
+});
+program
+    .command("init")
+    .description("Create a local .env file")
+    .option("--provider <provider>", "sqlite or supabase", "supabase")
+    .option("--url <url>", "Supabase project URL")
+    .option("--key <key>", "Supabase service-role or secret key")
+    .option("--sqlite-path <path>", "SQLite database path", defaultSqlitePath)
+    .option("--path <path>", "Env file path", ".env")
+    .option("--force", "Overwrite an existing env file", false)
+    .action(async (options) => {
+    await run(async () => {
+        const provider = parseProvider(options.provider);
+        const envPath = writeEnvFile({
+            provider,
+            path: options.path,
+            force: options.force,
+            supabaseUrl: options.url,
+            supabaseKey: options.key,
+            sqlitePath: options.sqlitePath
         });
-        printResult({ ok: true, path: envPath }, outputMode());
+        printResult({ ok: true, provider, path: envPath }, outputMode());
     });
 });
 program
@@ -35,14 +82,41 @@ program
     .description("Check local CLI configuration")
     .action(async () => {
     await run(async () => {
-        const config = getConfig();
+        const config = readConfig();
         printResult({
             ok: true,
-            supabaseUrl: config.SUPABASE_URL,
-            hasSupabaseKey: Boolean(config.SUPABASE_KEY)
+            provider: config.provider,
+            supabaseUrl: config.supabaseUrl,
+            hasSupabaseKey: Boolean(config.supabaseKey),
+            sqlitePath: config.sqlitePath
         }, outputMode());
     });
 });
+const db = program.command("db").description("Manage database schema");
+db.command("init")
+    .description("Initialize the configured database schema")
+    .action(async () => {
+    await run(async () => {
+        printResult(await setupDatabase(), outputMode());
+    });
+});
+db.command("status")
+    .description("Check whether required tables exist")
+    .action(async () => {
+    await run(async () => {
+        printResult(await checkDatabase(), outputMode());
+    });
+});
+db.command("schema")
+    .description("Print SQL schema for a provider")
+    .option("--provider <provider>", "sqlite or supabase")
+    .action(async (options) => {
+    await run(async () => {
+        const config = readConfig();
+        const provider = parseProvider(options.provider ?? config.provider);
+        printResult(schemaFor(provider), outputMode());
+    });
+});
 const people = program.command("people").description("Manage people");
 people
     .command("add")
@@ -138,6 +212,11 @@ function outputMode() {
     const mode = program.opts().output;
     return mode === "json" ? "json" : "table";
 }
+function parseProvider(value) {
+    if (value === "sqlite" || value === "supabase")
+        return value;
+    throw new Error("Provider must be sqlite or supabase.");
+}
 async function run(fn) {
     try {
         await fn();

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-export declare function getConfig(): {
-    SUPABASE_URL: string;
-    SUPABASE_KEY: string;
-};
+import type { RuntimeConfig } from "./types.js";
+export declare const defaultSqlitePath: string;
+export declare function readConfig(): RuntimeConfig;
+export declare function getConfig(): RuntimeConfig;

package/dist/config.js

@@ -8,14 +8,54 @@ const codexEnvPath = join(homedir(), ".codex", ".env");
 if (existsSync(codexEnvPath)) {
     loadDotenv({ path: codexEnvPath, override: false });
 }
+export const defaultSqlitePath = join(homedir(), ".people-truth", "people-truth.sqlite");
 const envSchema = z.object({
-    SUPABASE_URL: z.string().url(),
-    SUPABASE_KEY: z.string().min(1)
+    PEOPLE_TRUTH_PROVIDER: z.enum(["supabase", "sqlite"]).optional(),
+    PEOPLE_TRUTH_SQLITE_PATH: z.string().min(1).optional(),
+    SUPABASE_URL: z.string().url().optional(),
+    SUPABASE_KEY: z.string().min(1).optional()
 });
-export function getConfig() {
+export function readConfig() {
     const parsed = envSchema.safeParse(process.env);
     if (!parsed.success) {
-        throw new Error("Missing Supabase config. Set SUPABASE_URL and SUPABASE_KEY in .env or ~/.codex/.env.");
+        throw new Error("Invalid people-truth environment configuration.");
+    }
+    const env = parsed.data;
+    const provider = resolveProvider(env.PEOPLE_TRUTH_PROVIDER, env);
+    return {
+        provider,
+        supabaseUrl: env.SUPABASE_URL,
+        supabaseKey: env.SUPABASE_KEY,
+        sqlitePath: expandPath(env.PEOPLE_TRUTH_SQLITE_PATH ?? defaultSqlitePath)
+    };
+}
+export function getConfig() {
+    const config = readConfig();
+    if (config.provider === "supabase" && (!config.supabaseUrl || !config.supabaseKey)) {
+        throw new Error("Missing Supabase config. Run `ptruth setup --provider supabase` or set SUPABASE_URL and SUPABASE_KEY.");
     }
-    return parsed.data;
+    if (config.provider === "sqlite" && !config.sqlitePath) {
+        throw new Error("Missing SQLite config. Run `ptruth setup --provider sqlite` or set PEOPLE_TRUTH_SQLITE_PATH.");
+    }
+    return config;
+}
+function resolveProvider(provider, env) {
+    if (provider)
+        return provider;
+    if (env.PEOPLE_TRUTH_SQLITE_PATH)
+        return "sqlite";
+    if (env.SUPABASE_URL || env.SUPABASE_KEY)
+        return "supabase";
+    return "sqlite";
+}
+function expandPath(value) {
+    if (value === "~")
+        return homedir();
+    if (value.startsWith("~/"))
+        return join(homedir(), value.slice(2));
+    if (value === "$HOME")
+        return homedir();
+    if (value.startsWith("$HOME/"))
+        return join(homedir(), value.slice(6));
+    return value;
 }

package/dist/facts.d.ts

@@ -1,11 +1,3 @@
-export declare function addFact(input: {
-    person: string;
-    predicate: string;
-    value: string;
-    confidence: "confirmed" | "likely" | "unverified";
-    sourceType?: string;
-    sourceRef?: string;
-    sourceTitle?: string;
-    sourceUrl?: string;
-}): Promise<any>;
-export declare function listFacts(identifier: string): Promise<any>;
+import type { AddFactInput } from "./types.js";
+export declare function addFact(input: AddFactInput): Promise<unknown>;
+export declare function listFacts(identifier: string): Promise<unknown[]>;

package/dist/facts.js

@@ -1,44 +1,7 @@
-import { getPerson } from "./people.js";
-import { getSupabase } from "./supabase.js";
+import { getStore } from "./store.js";
 export async function addFact(input) {
-    const supabase = getSupabase();
-    const person = await getPerson(input.person);
-    if (!person)
-        throw new Error(`Person not found: ${input.person}`);
-    let sourceId = null;
-    if (input.sourceType || input.sourceRef || input.sourceTitle || input.sourceUrl) {
-        const { data: source, error: sourceError } = await supabase
-            .from("sources")
-            .insert({
-            source_type: input.sourceType ?? "manual",
-            source_ref: input.sourceRef,
-            title: input.sourceTitle,
-            url: input.sourceUrl
-        })
-            .select()
-            .single();
-        if (sourceError)
-            throw new Error(sourceError.message);
-        sourceId = source.id;
-    }
-    const { data, error } = await supabase
-        .from("person_facts")
-        .insert({
-        person_id: person.id,
-        predicate: input.predicate,
-        value: input.value,
-        confidence: input.confidence,
-        source_id: sourceId
-    })
-        .select("*, sources(source_type, source_ref, title, url)")
-        .single();
-    if (error)
-        throw new Error(error.message);
-    return data;
+    return getStore().addFact(input);
 }
 export async function listFacts(identifier) {
-    const person = await getPerson(identifier);
-    if (!person)
-        throw new Error(`Person not found: ${identifier}`);
-    return person.person_facts ?? [];
+    return getStore().listFacts(identifier);
 }

package/dist/people.d.ts

@@ -1,13 +1,5 @@
-export declare function addPerson(input: {
-    name: string;
-    aliases: string[];
-    organization?: string;
-    role?: string;
-    location?: string;
-    relationship?: string;
-    bio?: string;
-    note?: string;
-}): Promise<any>;
+import type { AddPersonInput } from "./types.js";
+export declare function addPerson(input: AddPersonInput): Promise<unknown>;
 export declare function searchPeople(query: string): Promise<unknown[]>;
 export declare function getPerson(identifier: string): Promise<any>;
 export declare function formatPersonMention(identifier: string, label?: string): Promise<string>;

package/dist/people.js

@@ -1,101 +1,12 @@
-import { getSupabase } from "./supabase.js";
-const PERSON_SELECT = "*, person_names(name, name_type, locale, is_primary), person_identifiers(identifier_type, value, url, is_primary), person_affiliations(organization_name, role_title, start_date, end_date, note), person_facts(id, predicate, value, confidence, valid_from, valid_to, created_at, sources(source_type, source_ref, title, url))";
+import { getStore } from "./store.js";
 export async function addPerson(input) {
-    const supabase = getSupabase();
-    const { data: person, error } = await supabase
-        .from("people")
-        .insert({
-        canonical_name: input.name,
-        display_name: input.name,
-        bio: input.bio,
-        note: input.note ?? ([input.location, input.relationship].filter(Boolean).join("; ") || undefined)
-    })
-        .select()
-        .single();
-    if (error)
-        throw new Error(error.message);
-    const names = Array.from(new Set([input.name, ...input.aliases].filter(Boolean)));
-    if (names.length > 0) {
-        const { error: nameError } = await supabase.from("person_names").insert(names.map((alias) => ({
-            person_id: person.id,
-            name: alias,
-            name_type: alias === input.name ? "canonical" : "alias",
-            is_primary: alias === input.name
-        })));
-        if (nameError)
-            throw new Error(nameError.message);
-    }
-    if (input.organization) {
-        const { error: affiliationError } = await supabase.from("person_affiliations").insert({
-            person_id: person.id,
-            organization_name: input.organization,
-            role_title: input.role
-        });
-        if (affiliationError)
-            throw new Error(affiliationError.message);
-    }
-    return getPerson(person.id);
+    return getStore().addPerson(input);
 }
 export async function searchPeople(query) {
-    const supabase = getSupabase();
-    const pattern = `%${query}%`;
-    const select = "id, canonical_name, display_name, bio, note, person_names(name, name_type), person_affiliations(organization_name, role_title)";
-    const { data: directMatches, error } = await supabase
-        .from("people")
-        .select(select)
-        .or(`canonical_name.ilike.${pattern},display_name.ilike.${pattern},bio.ilike.${pattern},note.ilike.${pattern}`)
-        .limit(20);
-    if (error)
-        throw new Error(error.message);
-    const { data: nameMatches, error: nameError } = await supabase
-        .from("person_names")
-        .select(`people(${select})`)
-        .ilike("name", pattern)
-        .limit(20);
-    if (nameError)
-        throw new Error(nameError.message);
-    const byId = new Map();
-    for (const person of directMatches ?? []) {
-        byId.set(person.id, person);
-    }
-    for (const row of nameMatches ?? []) {
-        const person = Array.isArray(row.people) ? row.people[0] : row.people;
-        if (person?.id)
-            byId.set(person.id, person);
-    }
-    return Array.from(byId.values()).slice(0, 20);
+    return getStore().searchPeople(query);
 }
 export async function getPerson(identifier) {
-    const supabase = getSupabase();
-    const { data: personById, error: idError } = await supabase
-        .from("people")
-        .select(PERSON_SELECT)
-        .eq("id", identifier)
-        .maybeSingle();
-    if (idError)
-        throw new Error(idError.message);
-    if (personById)
-        return personById;
-    const { data: nameMatches, error: aliasError } = await supabase
-        .from("person_names")
-        .select("person_id")
-        .ilike("name", identifier)
-        .limit(2);
-    if (aliasError)
-        throw new Error(aliasError.message);
-    if (!nameMatches || nameMatches.length === 0)
-        return null;
-    if (nameMatches.length > 1) {
-        throw new Error(`Multiple people match "${identifier}". Use a UUID instead.`);
-    }
-    const { data, error } = await supabase
-        .from("people")
-        .select(PERSON_SELECT)
-        .eq("id", nameMatches[0].person_id)
-        .single();
-    if (error)
-        throw new Error(error.message);
-    return data;
+    return getStore().getPerson(identifier);
 }
 export async function formatPersonMention(identifier, label) {
     const person = await getPerson(identifier);

package/dist/schema.d.ts

@@ -0,0 +1,5 @@
+import type { Provider } from "./types.js";
+export declare const requiredTables: string[];
+export declare function getSchema(provider: Provider): string;
+export declare function getSupabaseSchemaPath(): string;
+export declare const sqliteSchema = "\npragma foreign_keys = on;\n\ncreate table if not exists people (\n  id text primary key,\n  canonical_name text not null,\n  display_name text,\n  sort_name text,\n  avatar_url text,\n  bio text,\n  note text,\n  created_at text not null default current_timestamp,\n  updated_at text not null default current_timestamp\n);\n\ncreate table if not exists person_names (\n  id text primary key,\n  person_id text not null references people(id) on delete cascade,\n  name text not null,\n  name_type text not null default 'alias'\n    check (name_type in ('canonical', 'display', 'alias', 'nickname', 'courtesy_name', 'pen_name', 'former_name', 'foreign_name', 'other')),\n  locale text,\n  is_primary integer not null default 0,\n  created_at text not null default current_timestamp\n);\n\ncreate unique index if not exists person_names_unique_lower_name_type\n  on person_names (person_id, lower(name), name_type);\n\ncreate unique index if not exists person_names_primary_per_type\n  on person_names (person_id, name_type)\n  where is_primary = 1;\n\ncreate index if not exists person_names_name_idx\n  on person_names (name);\n\ncreate table if not exists person_identifiers (\n  id text primary key,\n  person_id text not null references people(id) on delete cascade,\n  identifier_type text not null,\n  value text not null,\n  url text,\n  is_primary integer not null default 0,\n  created_at text not null default current_timestamp,\n  unique (identifier_type, value)\n);\n\ncreate table if not exists person_affiliations (\n  id text primary key,\n  person_id text not null references people(id) on delete cascade,\n  organization_name text not null,\n  role_title text,\n  start_date text,\n  end_date text,\n  note text,\n  created_at text not null default current_timestamp\n);\n\ncreate table if not exists sources (\n  id text primary key,\n  source_type text not null default 'manual',\n  source_ref text,\n  title text,\n  url text,\n  captured_at text,\n  created_at text not null default current_timestamp\n);\n\ncreate table if not exists person_facts (\n  id text primary key,\n  person_id text not null references people(id) on delete cascade,\n  predicate text not null,\n  value text not null,\n  confidence text not null default 'unverified'\n    check (confidence in ('confirmed', 'likely', 'unverified')),\n  source_id text references sources(id) on delete set null,\n  valid_from text,\n  valid_to text,\n  created_at text not null default current_timestamp,\n  updated_at text not null default current_timestamp\n);\n\ncreate index if not exists people_canonical_name_idx\n  on people (canonical_name);\n\ncreate index if not exists people_display_name_idx\n  on people (display_name);\n\ncreate index if not exists person_identifiers_person_id\n  on person_identifiers (person_id);\n\ncreate index if not exists person_affiliations_person_id\n  on person_affiliations (person_id);\n\ncreate index if not exists person_facts_person_id_created_at\n  on person_facts (person_id, created_at desc);\n";

package/dist/schema.js

@@ -0,0 +1,117 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+export const requiredTables = [
+    "people",
+    "person_names",
+    "person_identifiers",
+    "person_affiliations",
+    "sources",
+    "person_facts"
+];
+export function getSchema(provider) {
+    if (provider === "sqlite")
+        return sqliteSchema;
+    return readFileSync(getSupabaseSchemaPath(), "utf8");
+}
+export function getSupabaseSchemaPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, "..", "supabase", "schema.sql");
+}
+export const sqliteSchema = `
+pragma foreign_keys = on;
+
+create table if not exists people (
+  id text primary key,
+  canonical_name text not null,
+  display_name text,
+  sort_name text,
+  avatar_url text,
+  bio text,
+  note text,
+  created_at text not null default current_timestamp,
+  updated_at text not null default current_timestamp
+);
+
+create table if not exists person_names (
+  id text primary key,
+  person_id text not null references people(id) on delete cascade,
+  name text not null,
+  name_type text not null default 'alias'
+    check (name_type in ('canonical', 'display', 'alias', 'nickname', 'courtesy_name', 'pen_name', 'former_name', 'foreign_name', 'other')),
+  locale text,
+  is_primary integer not null default 0,
+  created_at text not null default current_timestamp
+);
+
+create unique index if not exists person_names_unique_lower_name_type
+  on person_names (person_id, lower(name), name_type);
+
+create unique index if not exists person_names_primary_per_type
+  on person_names (person_id, name_type)
+  where is_primary = 1;
+
+create index if not exists person_names_name_idx
+  on person_names (name);
+
+create table if not exists person_identifiers (
+  id text primary key,
+  person_id text not null references people(id) on delete cascade,
+  identifier_type text not null,
+  value text not null,
+  url text,
+  is_primary integer not null default 0,
+  created_at text not null default current_timestamp,
+  unique (identifier_type, value)
+);
+
+create table if not exists person_affiliations (
+  id text primary key,
+  person_id text not null references people(id) on delete cascade,
+  organization_name text not null,
+  role_title text,
+  start_date text,
+  end_date text,
+  note text,
+  created_at text not null default current_timestamp
+);
+
+create table if not exists sources (
+  id text primary key,
+  source_type text not null default 'manual',
+  source_ref text,
+  title text,
+  url text,
+  captured_at text,
+  created_at text not null default current_timestamp
+);
+
+create table if not exists person_facts (
+  id text primary key,
+  person_id text not null references people(id) on delete cascade,
+  predicate text not null,
+  value text not null,
+  confidence text not null default 'unverified'
+    check (confidence in ('confirmed', 'likely', 'unverified')),
+  source_id text references sources(id) on delete set null,
+  valid_from text,
+  valid_to text,
+  created_at text not null default current_timestamp,
+  updated_at text not null default current_timestamp
+);
+
+create index if not exists people_canonical_name_idx
+  on people (canonical_name);
+
+create index if not exists people_display_name_idx
+  on people (display_name);
+
+create index if not exists person_identifiers_person_id
+  on person_identifiers (person_id);
+
+create index if not exists person_affiliations_person_id
+  on person_affiliations (person_id);
+
+create index if not exists person_facts_person_id_created_at
+  on person_facts (person_id, created_at desc);
+`;

package/dist/setup.d.ts

@@ -0,0 +1,19 @@
+import type { Provider, RuntimeConfig } from "./types.js";
+export interface WriteEnvInput {
+    provider: Provider;
+    path: string;
+    force?: boolean;
+    supabaseUrl?: string;
+    supabaseKey?: string;
+    sqlitePath?: string;
+}
+export declare function writeEnvFile(input: WriteEnvInput): string;
+export declare function setupDatabase(config?: RuntimeConfig): Promise<{
+    ok: boolean;
+    missingTables: string[];
+}>;
+export declare function checkDatabase(config?: RuntimeConfig): Promise<{
+    ok: boolean;
+    missingTables: string[];
+}>;
+export declare function schemaFor(provider: Provider): string;

package/dist/setup.js

@@ -0,0 +1,37 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { mkdirSync } from "node:fs";
+import { getSchema } from "./schema.js";
+import { getStore } from "./store.js";
+import { defaultSqlitePath, readConfig } from "./config.js";
+export function writeEnvFile(input) {
+    const envPath = resolve(input.path);
+    if (existsSync(envPath) && !input.force) {
+        throw new Error(`${envPath} already exists. Re-run with --force to overwrite it.`);
+    }
+    const sqlitePath = input.sqlitePath ?? defaultSqlitePath;
+    const lines = [`PEOPLE_TRUTH_PROVIDER="${input.provider}"`];
+    if (input.provider === "supabase") {
+        if (!input.supabaseUrl || !input.supabaseKey) {
+            throw new Error("Supabase setup requires --url and --key.");
+        }
+        lines.push(`SUPABASE_URL="${input.supabaseUrl}"`, `SUPABASE_KEY="${input.supabaseKey}"`);
+    }
+    else {
+        lines.push(`PEOPLE_TRUTH_SQLITE_PATH="${sqlitePath}"`);
+        mkdirSync(dirname(sqlitePath), { recursive: true });
+    }
+    writeFileSync(envPath, `${lines.join("\n")}\n`, { mode: 0o600 });
+    return envPath;
+}
+export async function setupDatabase(config = readConfig()) {
+    const store = getStore(config);
+    await store.initializeSchema();
+    return store.checkSchema();
+}
+export async function checkDatabase(config = readConfig()) {
+    return getStore(config).checkSchema();
+}
+export function schemaFor(provider) {
+    return getSchema(provider);
+}

package/dist/store.d.ts

@@ -0,0 +1,2 @@
+import type { PeopleTruthStore, RuntimeConfig } from "./types.js";
+export declare function getStore(config?: RuntimeConfig): PeopleTruthStore;

package/dist/store.js

@@ -0,0 +1,12 @@
+import { getConfig } from "./config.js";
+import { getSupabase } from "./supabase.js";
+import { SqliteStore } from "./stores/sqlite-store.js";
+import { SupabaseStore } from "./stores/supabase-store.js";
+export function getStore(config = getConfig()) {
+    if (config.provider === "sqlite") {
+        if (!config.sqlitePath)
+            throw new Error("Missing SQLite database path.");
+        return new SqliteStore(config.sqlitePath);
+    }
+    return new SupabaseStore(getSupabase(config));
+}

package/dist/stores/sqlite-store.d.ts

@@ -0,0 +1,20 @@
+import type { AddFactInput, AddPersonInput, PeopleTruthStore } from "../types.js";
+export declare class SqliteStore implements PeopleTruthStore {
+    readonly sqlitePath: string;
+    readonly provider = "sqlite";
+    private readonly db;
+    constructor(sqlitePath: string);
+    initializeSchema(): Promise<void>;
+    checkSchema(): Promise<{
+        ok: boolean;
+        missingTables: string[];
+    }>;
+    addPerson(input: AddPersonInput): Promise<any>;
+    searchPeople(query: string): Promise<any[]>;
+    getPerson(identifier: string): Promise<any>;
+    addFact(input: AddFactInput): Promise<any>;
+    listFacts(identifier: string): Promise<any>;
+    close(): void;
+    private getPersonById;
+    private getFactById;
+}

package/dist/stores/sqlite-store.js

@@ -0,0 +1,172 @@
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { requiredTables, sqliteSchema } from "../schema.js";
+export class SqliteStore {
+    sqlitePath;
+    provider = "sqlite";
+    db;
+    constructor(sqlitePath) {
+        this.sqlitePath = sqlitePath;
+        mkdirSync(dirname(sqlitePath), { recursive: true });
+        this.db = new Database(sqlitePath);
+        this.db.pragma("foreign_keys = ON");
+    }
+    async initializeSchema() {
+        this.db.exec(sqliteSchema);
+    }
+    async checkSchema() {
+        const existing = new Set(this.db
+            .prepare("select name from sqlite_master where type = 'table'")
+            .all()
+            .map((row) => row.name));
+        const missingTables = requiredTables.filter((table) => !existing.has(table));
+        return { ok: missingTables.length === 0, missingTables };
+    }
+    async addPerson(input) {
+        const id = randomUUID();
+        const note = input.note ?? ([input.location, input.relationship].filter(Boolean).join("; ") || undefined);
+        const createPerson = this.db.transaction(() => {
+            this.db
+                .prepare("insert into people (id, canonical_name, display_name, bio, note) values (?, ?, ?, ?, ?)")
+                .run(id, input.name, input.name, input.bio ?? null, note ?? null);
+            const insertName = this.db.prepare("insert into person_names (id, person_id, name, name_type, is_primary) values (?, ?, ?, ?, ?)");
+            const names = Array.from(new Set([input.name, ...input.aliases].filter(Boolean)));
+            for (const alias of names) {
+                insertName.run(randomUUID(), id, alias, alias === input.name ? "canonical" : "alias", alias === input.name ? 1 : 0);
+            }
+            if (input.organization) {
+                this.db
+                    .prepare("insert into person_affiliations (id, person_id, organization_name, role_title) values (?, ?, ?, ?)")
+                    .run(randomUUID(), id, input.organization, input.role ?? null);
+            }
+        });
+        createPerson();
+        return this.getPerson(id);
+    }
+    async searchPeople(query) {
+        const pattern = `%${query.toLowerCase()}%`;
+        const rows = this.db
+            .prepare(`
+        select distinct p.id
+        from people p
+        left join person_names pn on pn.person_id = p.id
+        where lower(p.canonical_name) like ?
+           or lower(coalesce(p.display_name, '')) like ?
+           or lower(coalesce(p.bio, '')) like ?
+           or lower(coalesce(p.note, '')) like ?
+           or lower(coalesce(pn.name, '')) like ?
+        order by p.created_at desc
+        limit 20
+        `)
+            .all(pattern, pattern, pattern, pattern, pattern);
+        const people = [];
+        for (const row of rows) {
+            const person = await this.getPerson(row.id);
+            if (person)
+                people.push(compactPerson(person));
+        }
+        return people;
+    }
+    async getPerson(identifier) {
+        const byId = this.getPersonById(identifier);
+        if (byId)
+            return byId;
+        const nameMatches = this.db
+            .prepare("select distinct person_id from person_names where lower(name) = lower(?) limit 2")
+            .all(identifier);
+        if (nameMatches.length === 0)
+            return null;
+        if (nameMatches.length > 1) {
+            throw new Error(`Multiple people match "${identifier}". Use a UUID instead.`);
+        }
+        return this.getPersonById(nameMatches[0].person_id);
+    }
+    async addFact(input) {
+        const person = await this.getPerson(input.person);
+        if (!person)
+            throw new Error(`Person not found: ${input.person}`);
+        const factId = randomUUID();
+        const addFact = this.db.transaction(() => {
+            let sourceId = null;
+            if (input.sourceType || input.sourceRef || input.sourceTitle || input.sourceUrl) {
+                sourceId = randomUUID();
+                this.db
+                    .prepare("insert into sources (id, source_type, source_ref, title, url) values (?, ?, ?, ?, ?)")
+                    .run(sourceId, input.sourceType ?? "manual", input.sourceRef ?? null, input.sourceTitle ?? null, input.sourceUrl ?? null);
+            }
+            this.db
+                .prepare("insert into person_facts (id, person_id, predicate, value, confidence, source_id) values (?, ?, ?, ?, ?, ?)")
+                .run(factId, person.id, input.predicate, input.value, input.confidence, sourceId);
+        });
+        addFact();
+        return this.getFactById(factId);
+    }
+    async listFacts(identifier) {
+        const person = await this.getPerson(identifier);
+        if (!person)
+            throw new Error(`Person not found: ${identifier}`);
+        return person.person_facts ?? [];
+    }
+    close() {
+        this.db.close();
+    }
+    getPersonById(id) {
+        const person = this.db.prepare("select * from people where id = ?").get(id);
+        if (!person)
+            return null;
+        person.person_names = this.db
+            .prepare("select name, name_type, locale, is_primary from person_names where person_id = ? order by is_primary desc, created_at asc")
+            .all(id)
+            .map(booleanizePrimary);
+        person.person_identifiers = this.db
+            .prepare("select identifier_type, value, url, is_primary from person_identifiers where person_id = ? order by is_primary desc, created_at asc")
+            .all(id)
+            .map(booleanizePrimary);
+        person.person_affiliations = this.db
+            .prepare("select organization_name, role_title, start_date, end_date, note from person_affiliations where person_id = ? order by created_at desc")
+            .all(id);
+        person.person_facts = this.db
+            .prepare(`
+        select pf.*, s.source_type, s.source_ref, s.title as source_title, s.url as source_url
+        from person_facts pf
+        left join sources s on s.id = pf.source_id
+        where pf.person_id = ?
+        order by pf.created_at desc
+        `)
+            .all(id)
+            .map(formatFact);
+        return person;
+    }
+    getFactById(id) {
+        const row = this.db
+            .prepare(`
+        select pf.*, s.source_type, s.source_ref, s.title as source_title, s.url as source_url
+        from person_facts pf
+        left join sources s on s.id = pf.source_id
+        where pf.id = ?
+        `)
+            .get(id);
+        return row ? formatFact(row) : null;
+    }
+}
+function booleanizePrimary(row) {
+    return { ...row, is_primary: Boolean(row.is_primary) };
+}
+function formatFact(row) {
+    const source = row.source_id && row.source_type
+        ? {
+            source_type: row.source_type,
+            source_ref: row.source_ref,
+            title: row.source_title,
+            url: row.source_url
+        }
+        : null;
+    const { source_type, source_ref, source_title, source_url, ...fact } = row;
+    return { ...fact, sources: source };
+}
+function compactPerson(person) {
+    const { person_identifiers, person_facts, ...rest } = person;
+    return rest;
+}

package/dist/stores/supabase-store.d.ts

@@ -0,0 +1,18 @@
+import type { SupabaseClient } from "@supabase/supabase-js";
+import type { AddFactInput, AddPersonInput, PeopleTruthStore } from "../types.js";
+export declare class SupabaseStore implements PeopleTruthStore {
+    private readonly supabase;
+    readonly provider = "supabase";
+    constructor(supabase: SupabaseClient);
+    initializeSchema(): Promise<void>;
+    checkSchema(): Promise<{
+        ok: boolean;
+        missingTables: string[];
+    }>;
+    addPerson(input: AddPersonInput): Promise<any>;
+    searchPeople(query: string): Promise<unknown[]>;
+    getPerson(identifier: string): Promise<any>;
+    addFact(input: AddFactInput): Promise<any>;
+    listFacts(identifier: string): Promise<any>;
+}
+export declare function supabaseSchema(): string;

package/dist/stores/supabase-store.js

@@ -0,0 +1,159 @@
+import { getSchema, requiredTables } from "../schema.js";
+const PERSON_SELECT = "*, person_names(name, name_type, locale, is_primary), person_identifiers(identifier_type, value, url, is_primary), person_affiliations(organization_name, role_title, start_date, end_date, note), person_facts(id, predicate, value, confidence, valid_from, valid_to, created_at, sources(source_type, source_ref, title, url))";
+export class SupabaseStore {
+    supabase;
+    provider = "supabase";
+    constructor(supabase) {
+        this.supabase = supabase;
+    }
+    async initializeSchema() {
+        throw new Error("Supabase schema cannot be applied through the Data API. Run `ptruth db schema --provider supabase` and apply it in Supabase SQL editor, or use `supabase db push` from the repository.");
+    }
+    async checkSchema() {
+        const missingTables = [];
+        for (const table of requiredTables) {
+            const { error } = await this.supabase.from(table).select("*", { count: "exact", head: true });
+            if (error)
+                missingTables.push(table);
+        }
+        return { ok: missingTables.length === 0, missingTables };
+    }
+    async addPerson(input) {
+        const { data: person, error } = await this.supabase
+            .from("people")
+            .insert({
+            canonical_name: input.name,
+            display_name: input.name,
+            bio: input.bio,
+            note: input.note ?? ([input.location, input.relationship].filter(Boolean).join("; ") || undefined)
+        })
+            .select()
+            .single();
+        if (error)
+            throw new Error(error.message);
+        const names = Array.from(new Set([input.name, ...input.aliases].filter(Boolean)));
+        if (names.length > 0) {
+            const { error: nameError } = await this.supabase.from("person_names").insert(names.map((alias) => ({
+                person_id: person.id,
+                name: alias,
+                name_type: alias === input.name ? "canonical" : "alias",
+                is_primary: alias === input.name
+            })));
+            if (nameError)
+                throw new Error(nameError.message);
+        }
+        if (input.organization) {
+            const { error: affiliationError } = await this.supabase.from("person_affiliations").insert({
+                person_id: person.id,
+                organization_name: input.organization,
+                role_title: input.role
+            });
+            if (affiliationError)
+                throw new Error(affiliationError.message);
+        }
+        return this.getPerson(person.id);
+    }
+    async searchPeople(query) {
+        const pattern = `%${query}%`;
+        const select = "id, canonical_name, display_name, bio, note, person_names(name, name_type), person_affiliations(organization_name, role_title)";
+        const { data: directMatches, error } = await this.supabase
+            .from("people")
+            .select(select)
+            .or(`canonical_name.ilike.${pattern},display_name.ilike.${pattern},bio.ilike.${pattern},note.ilike.${pattern}`)
+            .limit(20);
+        if (error)
+            throw new Error(error.message);
+        const { data: nameMatches, error: nameError } = await this.supabase
+            .from("person_names")
+            .select(`people(${select})`)
+            .ilike("name", pattern)
+            .limit(20);
+        if (nameError)
+            throw new Error(nameError.message);
+        const byId = new Map();
+        for (const person of directMatches ?? []) {
+            byId.set(person.id, person);
+        }
+        for (const row of nameMatches ?? []) {
+            const person = Array.isArray(row.people) ? row.people[0] : row.people;
+            if (person?.id)
+                byId.set(person.id, person);
+        }
+        return Array.from(byId.values()).slice(0, 20);
+    }
+    async getPerson(identifier) {
+        const { data: personById, error: idError } = await this.supabase
+            .from("people")
+            .select(PERSON_SELECT)
+            .eq("id", identifier)
+            .maybeSingle();
+        if (idError)
+            throw new Error(idError.message);
+        if (personById)
+            return personById;
+        const { data: nameMatches, error: aliasError } = await this.supabase
+            .from("person_names")
+            .select("person_id")
+            .ilike("name", identifier)
+            .limit(2);
+        if (aliasError)
+            throw new Error(aliasError.message);
+        if (!nameMatches || nameMatches.length === 0)
+            return null;
+        if (nameMatches.length > 1) {
+            throw new Error(`Multiple people match "${identifier}". Use a UUID instead.`);
+        }
+        const { data, error } = await this.supabase
+            .from("people")
+            .select(PERSON_SELECT)
+            .eq("id", nameMatches[0].person_id)
+            .single();
+        if (error)
+            throw new Error(error.message);
+        return data;
+    }
+    async addFact(input) {
+        const person = await this.getPerson(input.person);
+        if (!person)
+            throw new Error(`Person not found: ${input.person}`);
+        let sourceId = null;
+        if (input.sourceType || input.sourceRef || input.sourceTitle || input.sourceUrl) {
+            const { data: source, error: sourceError } = await this.supabase
+                .from("sources")
+                .insert({
+                source_type: input.sourceType ?? "manual",
+                source_ref: input.sourceRef,
+                title: input.sourceTitle,
+                url: input.sourceUrl
+            })
+                .select()
+                .single();
+            if (sourceError)
+                throw new Error(sourceError.message);
+            sourceId = source.id;
+        }
+        const { data, error } = await this.supabase
+            .from("person_facts")
+            .insert({
+            person_id: person.id,
+            predicate: input.predicate,
+            value: input.value,
+            confidence: input.confidence,
+            source_id: sourceId
+        })
+            .select("*, sources(source_type, source_ref, title, url)")
+            .single();
+        if (error)
+            throw new Error(error.message);
+        return data;
+    }
+    async listFacts(identifier) {
+        const person = await this.getPerson(identifier);
+        if (!person)
+            throw new Error(`Person not found: ${identifier}`);
+        return person.person_facts ?? [];
+    }
+}
+export function supabaseSchema() {
+    return getSchema("supabase");
+}

package/dist/supabase.d.ts

@@ -1 +1,2 @@
-export declare function getSupabase(): import("@supabase/supabase-js").SupabaseClient<any, "public", "public", any, any>;
+import type { RuntimeConfig } from "./types.js";
+export declare function getSupabase(config?: RuntimeConfig): import("@supabase/supabase-js").SupabaseClient<any, "public", "public", any, any>;

package/dist/supabase.js

@@ -1,8 +1,10 @@
 import { createClient } from "@supabase/supabase-js";
 import { getConfig } from "./config.js";
-export function getSupabase() {
-    const { SUPABASE_URL, SUPABASE_KEY } = getConfig();
-    return createClient(SUPABASE_URL, SUPABASE_KEY, {
+export function getSupabase(config = getConfig()) {
+    if (!config.supabaseUrl || !config.supabaseKey) {
+        throw new Error("Missing Supabase config. Run `ptruth setup --provider supabase`.");
+    }
+    return createClient(config.supabaseUrl, config.supabaseKey, {
         auth: {
             persistSession: false,
             autoRefreshToken: false

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+export type Provider = "supabase" | "sqlite";
+export type Confidence = "confirmed" | "likely" | "unverified";
+export interface RuntimeConfig {
+    provider: Provider;
+    supabaseUrl?: string;
+    supabaseKey?: string;
+    sqlitePath?: string;
+}
+export interface AddPersonInput {
+    name: string;
+    aliases: string[];
+    organization?: string;
+    role?: string;
+    location?: string;
+    relationship?: string;
+    bio?: string;
+    note?: string;
+}
+export interface AddFactInput {
+    person: string;
+    predicate: string;
+    value: string;
+    confidence: Confidence;
+    sourceType?: string;
+    sourceRef?: string;
+    sourceTitle?: string;
+    sourceUrl?: string;
+}
+export interface PeopleTruthStore {
+    provider: Provider;
+    initializeSchema(): Promise<void>;
+    checkSchema(): Promise<{
+        ok: boolean;
+        missingTables: string[];
+    }>;
+    addPerson(input: AddPersonInput): Promise<unknown>;
+    searchPeople(query: string): Promise<unknown[]>;
+    getPerson(identifier: string): Promise<any | null>;
+    addFact(input: AddFactInput): Promise<unknown>;
+    listFacts(identifier: string): Promise<unknown[]>;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "people-truth",
-  "version": "1.0.0",
-  "description": "A Supabase-backed personal source of truth for people and relationship facts.",
+  "version": "1.1.3",
+  "description": "A portable source of truth for people and relationship facts backed by SQLite or Supabase.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -20,6 +20,8 @@
     "dist",
     "supabase",
     "skills",
+    ".env.example",
+    "sample.env",
     "README.md",
     "LICENSE"
   ],
@@ -35,10 +37,12 @@
     "prepack": "npm run build",
     "release": "semantic-release",
     "start": "node dist/cli.js",
+    "test": "npm run build && node --test test/*.test.mjs",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@supabase/supabase-js": "^2.108.1",
+    "better-sqlite3": "^12.10.0",
     "commander": "^12.1.0",
     "dotenv": "^16.6.1",
     "zod": "^3.25.76"
@@ -50,6 +54,7 @@
     "@semantic-release/github": "^12.0.8",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.10.2",
     "conventional-changelog-conventionalcommits": "^9.3.1",
     "semantic-release": "^25.0.5",

package/sample.env

@@ -0,0 +1,7 @@
+PEOPLE_TRUTH_PROVIDER="sqlite"
+PEOPLE_TRUTH_SQLITE_PATH="$HOME/.people-truth/people-truth.sqlite"
+
+# For Supabase:
+# PEOPLE_TRUTH_PROVIDER="supabase"
+# SUPABASE_URL="https://your-project-ref.supabase.co"
+# SUPABASE_KEY="your-service-role-or-secret-key"

package/skills/people-truth/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: people-truth
-description: Use the people-truth CLI and Supabase/Postgres schema when Codex needs to create, query, migrate, or reason about stable person identities, names, markdown person mentions, affiliations, identifiers, and sourced person facts in this repository or an installed people-truth CLI.
+description: Use the people-truth CLI and SQLite or Supabase/Postgres schema when Codex needs to create, query, migrate, or reason about stable person identities, names, markdown person mentions, affiliations, identifiers, and sourced person facts in this repository or an installed people-truth CLI.
 ---
 
 # People Truth
 
 ## Core Model
 
-Treat Supabase as a replaceable Postgres runtime. The durable contract is the migration SQL and CLI behavior in this repository.
+Treat SQLite as the local-first default and Supabase as a replaceable hosted Postgres runtime. The durable contract is the schema and CLI behavior in this repository.
 
 - `people.id` is the stable UUID identity.
 - `person_names` stores canonical names, display names, aliases, pen names, former names, foreign names, and other human labels.
@@ -29,7 +29,7 @@ Preserve the display label as written. Resolve the `person:uuid` target when cur
 Use `ptruth` when installed globally, or `npm run dev --` inside the repository.
 
 ```bash
-ptruth init --url "$SUPABASE_URL" --key "$SUPABASE_KEY"
+ptruth setup --provider sqlite
 ptruth status
 ptruth people add "梁启超" --alias "梁任公" --alias "饮冰室主人"
 ptruth people search "梁任公"
@@ -39,11 +39,19 @@ ptruth facts add "梁启超" wrote "饮冰室合集" --source manual --confidenc
 ptruth facts list "梁启超" -o json
 ```
 
+For Supabase:
+
+```bash
+ptruth setup --provider supabase --url "$SUPABASE_URL" --key "$SUPABASE_KEY"
+ptruth db status
+ptruth db schema --provider supabase
+```
+
 When writing automation or agent integrations, prefer `-o json` and parse stdout as JSON.
 
 ## Migration Workflow
 
-Use `supabase/migrations/*.sql` as the source of truth. Keep `supabase/schema.sql` as a readable flattened snapshot of the current schema.
+Use `ptruth db init` for SQLite. Use `supabase/migrations/*.sql` as the Supabase source of truth. Keep `supabase/schema.sql` as a readable flattened snapshot of the hosted schema.
 
 For local or linked Supabase projects: