@sqaoss/flowy 1.10.0 → 1.12.0

package/README.md

@@ -108,6 +108,41 @@ A manifest looks like:
 
 Each node's `parent` implies a `part_of` edge, so the simplest manifests need no explicit `edges`. `blocks` dependencies go in `edges`. The reserved `__flowyKey` metadata field stores the client-key; your own `metadata` is preserved alongside it and stripped back out on export.
 
+### Backup and restore (local SQLite)
+
+In self-hosted mode your backlog lives in a single SQLite file (see [Where your data lives](#where-your-data-lives)). `flowy backup` takes a consistent, file-level snapshot of that database, and `flowy restore` reinstates one.
+
+```bash
+flowy backup flowy-backup.sqlite             # snapshot the local DB (./flowy.sqlite by default)
+flowy backup ~/snapshots/flowy.sqlite --db ~/flowy.sqlite   # back up a DB at a custom path
+flowy restore flowy-backup.sqlite            # restore into a fresh DB (refuses to clobber)
+flowy restore flowy-backup.sqlite --force    # overwrite an existing DB
+```
+
+The snapshot is taken with SQLite's `VACUUM INTO`, so it is transactionally consistent **even while the server is running** and writes a single self-contained file (no `-wal`/`-shm` sidecars). `restore` validates the source is a real SQLite database before touching the target, and **refuses to overwrite an existing database** unless you pass `--force`.
+
+Both commands resolve the database path the same way the server does: `--db <path>`, then `$FLOWY_DB_PATH`, then `./flowy.sqlite`.
+
+**`backup` vs. `export` — they're complementary, not redundant:**
+
+| | `flowy export` (logical) | `flowy backup` (raw) |
+|---|---|---|
+| Format | Portable JSON manifest | Exact SQLite file |
+| Scope | The active project's subtree | The entire database (all projects) |
+| Re-importable | Yes — `flowy import` (idempotent, cross-backend) | No — restore only, local server |
+| Use it for | Migrating between machines/backends, re-importing, diffing in git | Point-in-time disaster recovery, an exact byte-faithful snapshot |
+
+Use `export`/`import` to move a backlog around or seed another backend; use `backup`/`restore` for a true snapshot of your local server's data.
+
+### Where your data lives
+
+The self-hosted server persists everything in one SQLite file. Its location depends on how you run the server:
+
+- **`flowy serve`** (native): `./flowy.sqlite` in the current directory by default, or wherever `--db`/`$FLOWY_DB_PATH` points.
+- **Docker (`docker compose up`)**: inside the named volume `flowy-data`, mounted at `/data`, with `FLOWY_DB_PATH=/data/flowy.sqlite`. The data outlives the container — but `docker compose down -v` deletes the volume **and your backlog with it**. Take a `flowy backup` first.
+
+To back up the Docker volume's database, point `--db` at the in-container path while running `flowy backup` from inside the container, or restore into a fresh `flowy serve` directory and snapshot there.
+
 ## Agent Skill
 
 `flowy setup` installs an agent skill so your AI agent automatically knows every command. If that install step fails (offline, no `npx`, registry hiccup), setup prints a warning telling you to install it manually:
@@ -145,7 +180,9 @@ flowy serve                  # bind 127.0.0.1:4000, store data in ./flowy.sqlite
 flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite   # override defaults
 ```
 
-The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, and `import`/`export`. Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
+The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, `import`/`export`, and `backup`/`restore` (raw SQLite snapshots). Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
+
+The canonical status flow is `draft → pending_review → approved → in_progress → done`, plus `blocked` and `cancelled`. By default any status change is allowed (and the `status` command validates the value client-side). To make the local server *enforce* legal transitions — rejecting illegal jumps like `draft → done` with a `VALIDATION_ERROR` — start it with `FLOWY_ENFORCE_STATUS_LIFECYCLE=1`. Enforcement is opt-in and off by default.
 
 ## Command Reference
 
@@ -179,10 +216,12 @@ The self-hosted server supports the full planning workflow — `init`, `project`
 | `task deps <id>` | Show what blocks a task and what it blocks |
 | `status <id> <status>` | Update status (shorthand) |
 | `approve <id>` | Approve (must be pending_review) |
-| `search <query> [--type] [--status] [--limit]` | Full-text search |
+| `search <query> [--type] [--status] [--limit]` | Full-text search; prints `{ nodes, truncated, total }` and warns on stderr when results are capped at `--limit` |
 | `tree <id> [--depth N]` | Show subtree from any entity |
 | `import <manifest>` | Ingest a JSON manifest of nodes + edges (idempotent by client-key) |
 | `export [output]` | Dump the active project as a manifest (stdout or file) |
+| `backup <dest> [--db <path>]` | Consistent file-level snapshot of the local SQLite database |
+| `restore <src> [--db <path>] [--force]` | Restore the local SQLite database from a backup (refuses to clobber without `--force`) |
 | `whoami` | Show current user (remote mode) |
 | `billing checkout --tier <tier>` | Get a checkout URL for a subscription (remote mode) |
 | `key rotate` | Revoke all API keys and issue a new one (remote mode) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "check": "biome check --write .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.config.e2e.ts",
     "sdl": "bun scripts/print-sdl.ts",
     "typecheck": "tsc --noEmit",
@@ -64,11 +65,12 @@
     "@commitlint/config-conventional": "^20.4.2",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
+    "@vitest/coverage-v8": "4.1.8",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
     "semantic-release": "25.0.3",
     "typescript": "^5",
-    "vitest": "^4.1.2"
+    "vitest": "4.1.8"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx}": [

package/server/src/contract.test.ts

@@ -360,11 +360,22 @@ describe('CLI/local-server contract (P1-1)', () => {
     })
     expect(Array.isArray(exportEdges.edges)).toBe(true)
 
-    const search = await ok<{ search: Array<{ id: string }> }>(
-      LOCAL_CONTRACT_OPERATIONS.SEARCH,
-      { query: 'Contract', type: 'project', status: null, limit: 50 },
-    )
-    expect(search.search.some((n) => n.id === project.id)).toBe(true)
+    // SEARCH returns a SearchResult envelope (F32): nodes + truncation meta.
+    const search = await ok<{
+      search: {
+        nodes: Array<{ id: string }>
+        truncated: boolean
+        total: number
+      }
+    }>(LOCAL_CONTRACT_OPERATIONS.SEARCH, {
+      query: 'Contract',
+      type: 'project',
+      status: null,
+      limit: 50,
+    })
+    expect(search.search.nodes.some((n) => n.id === project.id)).toBe(true)
+    expect(search.search.truncated).toBe(false)
+    expect(typeof search.search.total).toBe('number')
 
     // auditLog (P1-2/F27): the task has accumulated a trail — a `create` on
     // insert, a `status_change` to pending_review, an `approve`, plus the

package/server/src/index.errors.test.ts

@@ -29,9 +29,12 @@ describe('server error masking', () => {
   it('surfaces a too-short search error with real message and VALIDATION_ERROR code', async () => {
     instance = createServer({ dbPath: ':memory:', port: 0 })
 
-    const json = await gql('query ($q: String!) { search(query: $q) { id } }', {
-      q: 'ab',
-    })
+    const json = await gql(
+      'query ($q: String!) { search(query: $q) { nodes { id } } }',
+      {
+        q: 'ab',
+      },
+    )
 
     expect(json.errors).toBeDefined()
     const error = json.errors![0]

package/server/src/index.ts

@@ -7,15 +7,24 @@ export function createServer(opts?: {
   dbPath?: string
   port?: number
   hostname?: string
+  enforceStatusLifecycle?: boolean
 }) {
   const dbPath = opts?.dbPath ?? process.env.FLOWY_DB_PATH ?? './flowy.sqlite'
   const port = opts?.port ?? Number(process.env.PORT ?? 4000)
   // Bind loopback by default so the unauthenticated dev server is not exposed
   // on the LAN. Override with the `hostname` opt or the HOST env var.
   const hostname = opts?.hostname ?? process.env.HOST ?? '127.0.0.1'
+  // Status-lifecycle enforcement is OPT-IN (F32). Off unless explicitly enabled
+  // via the `enforceStatusLifecycle` opt or FLOWY_ENFORCE_STATUS_LIFECYCLE=1
+  // (also accepts "true"). When off, any vocabulary-valid status is accepted.
+  const enforceStatusLifecycle =
+    opts?.enforceStatusLifecycle ??
+    ['1', 'true'].includes(
+      (process.env.FLOWY_ENFORCE_STATUS_LIFECYCLE ?? '').toLowerCase(),
+    )
 
   const db = createDb(dbPath)
-  const resolvers = createResolvers(db)
+  const resolvers = createResolvers(db, { enforceStatusLifecycle })
 
   const yoga = createYoga({
     schema: createSchema({ typeDefs, resolvers }),

package/server/src/resolvers.test.ts

@@ -773,8 +773,10 @@ describe('createResolvers', () => {
       })
 
       const results = resolvers.Query.search(null, { query: 'Auth' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Authentication')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Authentication')
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(1)
     })
 
     it('finds nodes by description', () => {
@@ -785,8 +787,8 @@ describe('createResolvers', () => {
       })
 
       const results = resolvers.Query.search(null, { query: 'OAuth' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Login')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Login')
     })
 
     it('filters by type', () => {
@@ -803,8 +805,8 @@ describe('createResolvers', () => {
         query: 'Auth',
         type: 'project',
       })
-      expect(results).toHaveLength(1)
-      expect(results[0].type).toBe('project')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].type).toBe('project')
     })
 
     it('filters by status', () => {
@@ -825,8 +827,8 @@ describe('createResolvers', () => {
         query: 'Auth',
         status: 'in_progress',
       })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Auth')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Auth')
     })
 
     it('respects limit', () => {
@@ -841,7 +843,58 @@ describe('createResolvers', () => {
         query: 'Task',
         limit: 2,
       })
-      expect(results).toHaveLength(2)
+      expect(results.nodes).toHaveLength(2)
+    })
+
+    it('signals truncation when results are capped at the limit', () => {
+      for (let i = 0; i < 5; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 2,
+      })
+      expect(results.nodes).toHaveLength(2)
+      expect(results.truncated).toBe(true)
+      expect(results.total).toBe(5)
+    })
+
+    it('does not signal truncation when all results fit under the limit', () => {
+      for (let i = 0; i < 3; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 50,
+      })
+      expect(results.nodes).toHaveLength(3)
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(3)
+    })
+
+    it('does not signal truncation when results exactly equal the limit', () => {
+      for (let i = 0; i < 2; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 2,
+      })
+      expect(results.nodes).toHaveLength(2)
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(2)
     })
   })
 
@@ -958,7 +1011,9 @@ describe('createResolvers', () => {
       const results = resolvers.Query.search(null, {
         query: 'zzz_no_match',
       })
-      expect(results).toEqual([])
+      expect(results.nodes).toEqual([])
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(0)
     })
 
     it('throws when query is shorter than 3 characters', () => {
@@ -976,23 +1031,23 @@ describe('createResolvers', () => {
     it('succeeds with 3-character query', () => {
       create(resolvers, { type: 'project', title: 'abc match' })
       const results = resolvers.Query.search(null, { query: 'abc' })
-      expect(results).toHaveLength(1)
+      expect(results.nodes).toHaveLength(1)
     })
 
     it('does not treat % as LIKE wildcard', () => {
       create(resolvers, { type: 'project', title: '100% done' })
       create(resolvers, { type: 'project', title: '100 things' })
       const results = resolvers.Query.search(null, { query: '100%' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('100% done')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('100% done')
     })
 
     it('does not treat _ as LIKE wildcard', () => {
       create(resolvers, { type: 'project', title: '_est something' })
       create(resolvers, { type: 'project', title: 'Test something' })
       const results = resolvers.Query.search(null, { query: '_est' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('_est something')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('_est something')
     })
   })
 
@@ -1071,6 +1126,150 @@ describe('createResolvers', () => {
     })
   })
 
+  describe('status lifecycle enforcement (opt-in)', () => {
+    let strict: ReturnType<typeof createResolvers>
+
+    beforeEach(() => {
+      strict = createResolvers(db, { enforceStatusLifecycle: true })
+    })
+
+    function strictCreate(title: string): NodeGql {
+      return strict.Mutation.createNode(null, { type: 'task', title })
+    }
+
+    it('allows the canonical forward flow draft -> ... -> done', () => {
+      const node = strictCreate('Flow')
+      expect(node.status).toBe('draft')
+      let cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      expect(cur.status).toBe('pending_review')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'approved',
+      })
+      expect(cur.status).toBe('approved')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+      cur = strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      expect(cur.status).toBe('done')
+    })
+
+    it('rejects an illegal skip (draft -> done) with VALIDATION_ERROR', () => {
+      const node = strictCreate('Skip')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'done' }),
+      ).toThrow(/transition/i)
+      try {
+        strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      } catch (e) {
+        expect((e as { extensions?: { code?: string } }).extensions?.code).toBe(
+          'VALIDATION_ERROR',
+        )
+      }
+    })
+
+    it('rejects skipping pending_review -> in_progress', () => {
+      const node = strictCreate('Skip2')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      expect(() =>
+        strict.Mutation.updateNode(null, {
+          id: node.id,
+          status: 'in_progress',
+        }),
+      ).toThrow(/transition/i)
+    })
+
+    it('allows cancelling from an active state', () => {
+      const node = strictCreate('Cancel')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'cancelled',
+      })
+      expect(cur.status).toBe('cancelled')
+    })
+
+    it('allows blocking from in_progress and resuming', () => {
+      const node = strictCreate('Block')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'approved' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'in_progress' })
+      let cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'blocked',
+      })
+      expect(cur.status).toBe('blocked')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+    })
+
+    it('rejects blocking directly from draft', () => {
+      const node = strictCreate('BlockEarly')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'blocked' }),
+      ).toThrow(/transition/i)
+    })
+
+    it('allows reopening done -> in_progress', () => {
+      const node = strictCreate('Reopen')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'approved' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'in_progress' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+    })
+
+    it('allows a same-status no-op even under enforcement', () => {
+      const node = strictCreate('NoOp')
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'draft',
+      })
+      expect(cur.status).toBe('draft')
+    })
+
+    it('still validates the status vocabulary', () => {
+      const node = strictCreate('Vocab')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'bogus' }),
+      ).toThrow(/Invalid status/)
+    })
+
+    it('does NOT enforce transitions when the flag is off (default)', () => {
+      // default `resolvers` (no enforcement) permits the illegal skip
+      const node = create(resolvers, { type: 'task', title: 'Default' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'done',
+      })
+      expect(updated.status).toBe('done')
+    })
+  })
+
   describe('Query.descendants — edge cases', () => {
     it('returns empty array for leaf node', () => {
       const leaf = create(resolvers, { type: 'task', title: 'Leaf' })
@@ -1216,7 +1415,7 @@ describe('createResolvers', () => {
         query: 'Test',
         limit: 0,
       })
-      expect(results).toEqual([])
+      expect(results.nodes).toEqual([])
     })
   })
 

package/server/src/resolvers.ts

@@ -81,6 +81,18 @@ export interface SubtreeNodeGql extends NodeGql {
   relation: string
 }
 
+/**
+ * Search results plus truncation metadata (F32). `nodes` is capped at `limit`;
+ * `total` is the unbounded match count and `truncated` is true when `total`
+ * exceeds the returned page — letting the CLI show a clear "results truncated"
+ * marker instead of silently dropping matches at the default cap.
+ */
+export interface SearchResultGql {
+  nodes: NodeGql[]
+  truncated: boolean
+  total: number
+}
+
 interface SubtreeRow extends NodeRow {
   parent_id: string
   depth: number
@@ -114,6 +126,36 @@ function assertValidStatus(status: string): void {
   }
 }
 
+/**
+ * Allowed status transitions for the OPT-IN lifecycle enforcement
+ * (`FLOWY_ENFORCE_STATUS_LIFECYCLE`). The canonical forward flow is
+ * `draft → pending_review → approved → in_progress → done`; `blocked` and
+ * `cancelled` are reachable from active states and recoverable back into the
+ * flow. A same-status update is always a no-op and never checked here. When
+ * enforcement is OFF (the default) this map is unused and any vocabulary-valid
+ * status is accepted, preserving the prior behaviour.
+ */
+const ALLOWED_TRANSITIONS: Record<string, Set<string>> = {
+  draft: new Set(['pending_review', 'cancelled']),
+  pending_review: new Set(['approved', 'draft', 'cancelled']),
+  approved: new Set(['in_progress', 'pending_review', 'cancelled']),
+  in_progress: new Set(['done', 'blocked', 'cancelled']),
+  done: new Set(['in_progress']),
+  blocked: new Set(['in_progress', 'cancelled']),
+  cancelled: new Set(['draft']),
+}
+
+function assertValidTransition(from: string, to: string): void {
+  if (from === to) return
+  if (!ALLOWED_TRANSITIONS[from]?.has(to)) {
+    throw validationError(
+      `Illegal status transition: ${from} → ${to}. Allowed from "${from}": ${
+        [...(ALLOWED_TRANSITIONS[from] ?? [])].join(', ') || '(none)'
+      }`,
+    )
+  }
+}
+
 /**
  * Validate that `metadata` is a JSON string and return its canonical form.
  * Metadata is stored as a JSON string (the column and the GraphQL field are
@@ -216,7 +258,18 @@ function prefixedCols() {
     .join(', ')
 }
 
-export function createResolvers(db: Db) {
+export interface ResolverOptions {
+  /**
+   * Enforce the canonical status lifecycle on `updateNode` status changes.
+   * OFF by default — when false (the default) any vocabulary-valid status is
+   * accepted, matching pre-F32 behaviour. Wired from
+   * `FLOWY_ENFORCE_STATUS_LIFECYCLE` in `index.ts`.
+   */
+  enforceStatusLifecycle?: boolean
+}
+
+export function createResolvers(db: Db, opts: ResolverOptions = {}) {
+  const enforceStatusLifecycle = opts.enforceStatusLifecycle ?? false
   return {
     Query: {
       node: (_: unknown, args: { id: string }) => {
@@ -386,7 +439,7 @@ export function createResolvers(db: Db) {
           status?: string
           limit?: number
         },
-      ) => {
+      ): SearchResultGql => {
         if (args.query.trim().length < 3) {
           throw validationError('Search query must be at least 3 characters')
         }
@@ -403,13 +456,23 @@ export function createResolvers(db: Db) {
           conditions.push('status = ?')
           params.push(args.status)
         }
+        const where = conditions.join(' AND ')
         const limit = args.limit ?? 50
+        // Fetch one extra row so we can tell "exactly at the cap" from
+        // "more matches exist" without a second COUNT for the common case.
         const rows = db.raw
-          .query(
-            `SELECT ${NODE_COLS} FROM nodes WHERE ${conditions.join(' AND ')} LIMIT ?`,
-          )
-          .all(...params, limit) as NodeRow[]
-        return selectNodes(rows)
+          .query(`SELECT ${NODE_COLS} FROM nodes WHERE ${where} LIMIT ?`)
+          .all(...params, limit + 1) as NodeRow[]
+        const truncated = rows.length > limit
+        const page = truncated ? rows.slice(0, limit) : rows
+        const total = truncated
+          ? (
+              db.raw
+                .query(`SELECT COUNT(*) AS c FROM nodes WHERE ${where}`)
+                .get(...params) as { c: number }
+            ).c
+          : page.length
+        return { nodes: selectNodes(page), truncated, total }
       },
 
       // Audit history for a node, newest first. Shaped to match the SaaS
@@ -507,7 +570,12 @@ export function createResolvers(db: Db) {
         if (args.description != null && !args.description.trim()) {
           throw validationError('Description cannot be empty')
         }
-        if (args.status != null) assertValidStatus(args.status)
+        if (args.status != null) {
+          assertValidStatus(args.status)
+          if (enforceStatusLifecycle) {
+            assertValidTransition(existing.status, args.status)
+          }
+        }
 
         const next: NodeRow = {
           ...existing,

package/server/src/schema.ts

@@ -52,6 +52,16 @@ export const typeDefs = /* GraphQL */ `
     relation: String!
   }
 
+  # Search results plus truncation metadata (F32). \`nodes\` is the page capped
+  # at the requested \`limit\`; \`total\` is the unbounded match count and
+  # \`truncated\` is true when more matches exist than were returned, so the CLI
+  # can surface a "results truncated" marker instead of silently dropping rows.
+  type SearchResult {
+    nodes: [Node!]!
+    truncated: Boolean!
+    total: Int!
+  }
+
   type Query {
     node(id: String!): Node
     nodes(type: String): [Node!]!
@@ -59,7 +69,12 @@ export const typeDefs = /* GraphQL */ `
     subtree(nodeId: String!, relation: String, maxDepth: Int): [SubtreeNode!]!
     edges(nodeId: String!, relation: String!, direction: String): [Node!]!
     readyTasks(projectId: String): [Node!]!
-    search(query: String!, type: String, status: String, limit: Int): [Node!]!
+    search(
+      query: String!
+      type: String
+      status: String
+      limit: Int
+    ): SearchResult!
     auditLog(nodeId: String!, limit: Int): [AuditEntry!]!
   }
 

package/skills/using-flowy/SKILL.md

@@ -22,6 +22,7 @@ Flowy runs against one of two backends. Which one you're in determines which com
 | Account / API key | None | Email registration; API key stored in config |
 | Subscription | None — fully free | Data operations require an active subscription |
 | Planning workflow | Full (`init`, project/feature/task CRUD, status, approve, search, tree, `task deps`, `task list --ready/--all`, `import`/`export`) | Full, same commands |
+| `backup` / `restore` | Available (raw SQLite snapshot of the local DB) | **Not available** — local-only |
 | `whoami` / `billing` / `key` | **Not available** — these hard-fail locally | Available |
 
 The planning workflow is **identical** in both modes. Only the account/billing commands differ.
@@ -154,6 +155,9 @@ flowy status <id> done
 flowy search "query" --type task --status draft --limit 10
 flowy tree <id> --depth 3                    # show subtree from any entity
 ```
+`search` prints `{ nodes, truncated, total }`. When `truncated` is `true` the
+results were capped at `--limit` (default 50) and `total` more matches exist —
+raise `--limit` to see them.
 
 ### Import and Export
 ```bash
@@ -180,6 +184,19 @@ A manifest is a single JSON document describing a backlog: `nodes` (projects, fe
 
 **Idempotency:** import upserts by client-key — re-importing the same manifest updates the matching nodes in place instead of creating duplicates. The key is stored in node metadata under the reserved `__flowyKey` field (your own `metadata` is preserved alongside it and stripped back out on export). A node's `parent` implies a `part_of` edge, so simple manifests need no explicit `edges`; `blocks` dependencies are listed in `edges`. Edges live in the real edge model (`createEdge` / `Query.edges`), so a `blocks` edge created by hand with `task block` is captured on export and never re-created on the next import. Works in both local and remote modes.
 
+### Backup and Restore (local mode only)
+```bash
+flowy backup flowy-backup.sqlite             # consistent snapshot of the local SQLite DB
+flowy restore flowy-backup.sqlite            # restore into a fresh DB (refuses to clobber)
+flowy restore flowy-backup.sqlite --force    # overwrite an existing DB
+```
+
+`backup`/`restore` operate on the **raw SQLite file** the self-hosted server uses, resolving its path from `--db`, then `$FLOWY_DB_PATH`, then `./flowy.sqlite`. The snapshot is taken with SQLite `VACUUM INTO`, so it is consistent even while the server is running. `restore` refuses to overwrite an existing database without `--force`.
+
+This is **complementary to** `export`/`import`, not a replacement: `export` produces a portable, re-importable JSON manifest of one project (works in both modes); `backup` produces an exact, byte-faithful snapshot of the whole local database for disaster recovery (local mode only). Use `export` to move or seed a backlog; use `backup` for a true point-in-time snapshot.
+
+**Where the data lives:** in self-hosted mode the entire backlog is one SQLite file — `./flowy.sqlite` by default (or `$FLOWY_DB_PATH`). Under Docker it lives in the named volume `flowy-data` (mounted at `/data`, `FLOWY_DB_PATH=/data/flowy.sqlite`); `docker compose down -v` deletes that volume and the backlog with it, so take a `flowy backup` first.
+
 ### Remote-only (hosted mode)
 These hit account/billing resolvers that do **not** exist on the local server; they fail in local mode.
 ```bash