project-mgr 0.1.5 → 0.1.7

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## Unreleased
+## 0.1.7 - 2026-08-07
+
+### Added
+
+- Added project metadata management (`displayName`, `description`, `notes`) and fuzzy search via `projects` / `list --query`.
+- Added explicit field clearing for project metadata via `--clear-description` and `--clear-notes` flags in `pmgr set-project`.
+
+## 0.1.6 - 2026-08-03
+
+### Fixed
+
+- Allowed `history` to query recent entries across all projects without `--project`.
 
 ## 0.1.5 - 2026-08-03
 

package/README.md

@@ -45,7 +45,22 @@ The installer detects supported agents and asks where to install the skill. No s
 
 In Codex, write `$project-mgr` in the prompt. Alternatively, type `/pro` and select **project-mgr** from the picker. In other agents, use their explicit skill syntax or select `project-mgr` from the skills menu.
 
-For example: `Use $project-mgr to show this project's current status and recent history.`
+Use normal language after the skill name; the agent translates the request into CLI commands. For example:
+
+```text
+Use $project-mgr to show the current status and latest 10 updates for project-mgr.
+
+Use $project-mgr to record this update for project-mgr: active; released the Agent Skill;
+next, collect user feedback.
+
+Use $project-mgr to record these updates: api is blocked by authentication; web is active
+and the dashboard is complete.
+
+Use $project-mgr with PMGR_DB_PATH=/tmp/project-mgr-test.sqlite to add a test update,
+then show its history.
+```
+
+The agent should query before writing and ask for missing required values such as the project name, status, or summary.
 
 The skill uses the same `PMGR_DB_PATH` behavior as the CLI: it defaults to `~/.local/share/project-mgr/project-mgr.sqlite`; set an absolute path to work in another ledger. For manual or exploratory work, use a dedicated database such as `PMGR_DB_PATH=/tmp/project-mgr-skill-test.sqlite` rather than the default ledger.
 
@@ -142,6 +157,9 @@ pnpm start history \
   --limit 20 \
   --offset 0
 
+# Recent history across every project.
+pnpm start history --limit 20 --json
+
 pnpm start at \
   --project project-mgr \
   --at 2026-08-03T12:00:00+08:00 \
@@ -158,6 +176,8 @@ pnpm start at \
 
 Optional arguments:
 
+- `--description`: Project introduction or description (updates project metadata).
+- `--notes`: Project notes/remarks (updates project metadata).
 - `--progress`: Work already completed.
 - `--blocker`, `--next`, `--decision`, and `--tag`: May be specified repeatedly.
 - `--at`: When the status actually occurred. It must be an ISO 8601 timestamp with a timezone; defaults to the current time.
@@ -165,6 +185,29 @@ Optional arguments:
 - `--external-ref`: A globally idempotent key. A duplicate write to the same project returns the existing record; use by another project is an error.
 - `--json`: Emit stable JSON.
 
+### Project Metadata & Fuzzy Search
+
+Set or update a project's display name, description, and notes with `set-project`, or clear metadata using `--clear-description` / `--clear-notes`:
+
+```bash
+pnpm start set-project \
+  --project project-mgr \
+  --display-name "Project Manager" \
+  --description "Local-first append-only project status ledger" \
+  --notes "Core CLI and Agent Skill are published"
+
+# Clear description or notes
+pnpm start set-project --project project-mgr --clear-description --clear-notes
+```
+
+List projects or search projects using fuzzy matching across slug, display name, description, notes, latest status summary, and tags with `projects` (or `list`):
+
+```bash
+pnpm start projects
+pnpm start list --query "ledger"
+pnpm start projects --query "mvp" --json
+```
+
 ## Bulk import
 
 `import` accepts a JSON object, a JSON array, or a JSONL file containing one object per line. Every record is validated before the whole batch is written in one SQLite transaction; any failure rolls back the entire batch.
@@ -195,14 +238,16 @@ Unknown fields, unknown CLI options, extra positional arguments, invalid statuse
 
 ## Query and export
 
-| Command   | Purpose                                         | Key options                                                        |
-| --------- | ----------------------------------------------- | ------------------------------------------------------------------ |
-| `current` | Current status for all projects or one project  | `--project`, `--json`                                              |
-| `history` | One project's history, newest first             | `--project`, `--since`, `--until`, `--limit`, `--offset`, `--json` |
-| `at`      | The latest status at or before a specified time | `--project`, `--at`, `--json`                                      |
-| `export`  | Export all records or one project's records     | `--project`, `--format json\|jsonl`                                |
+| Command       | Purpose                                               | Key options                                                                                                 |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `projects`    | List all projects or fuzzy search by query            | `--query`, `--json`                                                                                         |
+| `set-project` | Set/update project display name, description, & notes | `--project`, `--display-name`, `--description`, `--notes`, `--clear-description`, `--clear-notes`, `--json` |
+| `current`     | Current status for all projects or one project        | `--project`, `--json`                                                                                       |
+| `history`     | History for all projects or one project, newest first | `--project`, `--since`, `--until`, `--limit`, `--offset`, `--json`                                          |
+| `at`          | The latest status at or before a specified time       | `--project`, `--at`, `--json`                                                                               |
+| `export`      | Export all records or one project's records           | `--project`, `--format json\|jsonl`                                                                         |
 
-All six actions can also use the compatible `status <action>` form, for example `pmgr status export`. Human-readable multi-record results list project, status, occurrence time, and summary, or `No entries found.` when empty. `add`, `import`, `current`, `history`, and `at` support `--json`; `export` uses `--format` to select its format.
+All actions can also use the compatible `status <action>` form, for example `pmgr status projects`. Human-readable multi-record results list projects and their latest status, or `No entries found.` / `No projects found.` when empty. `add`, `import`, `current`, `projects`, `list`, `set-project`, `history`, and `at` support `--json`; `export` uses `--format` to select its format.
 
 Exports omit the database-internal `id` and `recordedAt` fields and can be imported directly. Records are exported from oldest to newest so that restoring them preserves the insertion order of records with the same timestamp:
 

package/README_CN.md

@@ -45,7 +45,22 @@ npx skills add deanplus/project-manager
 
 在 Codex 的提示词中直接写 `$project-mgr`。也可以输入 `/pro`，然后在选择器中选择 **project-mgr**。其他 Agent 请使用其显式 Skill 语法，或从 Skills 菜单选择 `project-mgr`。
 
-例如：`使用 $project-mgr 查询当前项目状态和最近历史。`
+Skill 名称后直接使用自然语言即可，Agent 会把请求转换成 CLI 命令。例如：
+
+```text
+使用 $project-mgr 查询 project-mgr 的当前状态和最近 10 条更新。
+
+使用 $project-mgr 记录 project-mgr 的状态：active；已发布 Agent Skill；
+下一步收集用户反馈。
+
+使用 $project-mgr 批量记录状态：api 因认证问题 blocked；web 为 active，
+dashboard 已完成。
+
+使用 $project-mgr 和 PMGR_DB_PATH=/tmp/project-mgr-test.sqlite 添加一条测试状态，
+然后查询其历史。
+```
+
+Agent 应在写入前先查询；如果缺少项目名、状态或摘要等必填信息，它会向用户确认。
 
 该 Skill 与 CLI 使用相同的 `PMGR_DB_PATH` 规则：默认使用 `~/.local/share/project-mgr/project-mgr.sqlite`；如需使用其他账本，请设置绝对路径。手工或探索性操作请使用独立数据库，例如 `PMGR_DB_PATH=/tmp/project-mgr-skill-test.sqlite`，避免写入默认账本。
 
@@ -142,6 +157,9 @@ pnpm start history \
   --limit 20 \
   --offset 0
 
+# 查询全部项目的近期历史。
+pnpm start history --limit 20 --json
+
 pnpm start at \
   --project project-mgr \
   --at 2026-08-03T12:00:00+08:00 \
@@ -158,6 +176,8 @@ pnpm start at \
 
 可选参数：
 
+- `--description`：项目简介/描述（更新项目元数据）。
+- `--notes`：项目备注（更新项目元数据）。
 - `--progress`：已经完成的工作。
 - `--blocker`、`--next`、`--decision`、`--tag`：可以重复传入。
 - `--at`：状态实际发生时间，必须是带时区的 ISO 8601 时间；缺省为当前时间。
@@ -165,6 +185,29 @@ pnpm start at \
 - `--external-ref`：全局幂等键。重复写入同一项目时返回原记录；若被其他项目占用则报错。
 - `--json`：输出稳定 JSON。
 
+## 项目元数据与模糊查询
+
+可通过 `set-project` 设置或更新项目的名称、简介与备注，或使用 `--clear-description` / `--clear-notes` 清空：
+
+```bash
+pnpm start set-project \
+  --project project-mgr \
+  --display-name "Project Manager" \
+  --description "本地优先、只追加的项目状态账本" \
+  --notes "核心 CLI 与 Agent Skill 已上线"
+
+# 清空简介或备注
+pnpm start set-project --project project-mgr --clear-description --clear-notes
+```
+
+可通过 `projects`（或 `list`）列出所有项目或使用 `--query` 进行模糊匹配搜索（匹配项目名称 slug、显示名称、简介、备注、最新状态摘要及标签）：
+
+```bash
+pnpm start projects
+pnpm start list --query "账本"
+pnpm start projects --query "mvp" --json
+```
+
 ## 批量导入
 
 `import` 接受一个 JSON 对象、JSON 数组，或每行一个对象的 JSONL 文件。所有记录先校验，再在同一个 SQLite 事务中写入；任一记录失败时整批回滚。
@@ -195,14 +238,16 @@ pnpm start import --file statuses.jsonl --json
 
 ## 查询与导出
 
-| 命令      | 用途                       | 主要选项                                                           |
-| --------- | -------------------------- | ------------------------------------------------------------------ |
-| `current` | 所有项目或单项目的当前状态 | `--project`、`--json`                                              |
-| `history` | 单项目历史，最新记录在前   | `--project`、`--since`、`--until`、`--limit`、`--offset`、`--json` |
-| `at`      | 指定时间点及之前的最后状态 | `--project`、`--at`、`--json`                                      |
-| `export`  | 导出全部或单项目记录       | `--project`、`--format json\|jsonl`                                |
+| 命令          | 用途                                     | 主要选项                                                                                                    |
+| ------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `projects`    | 列出所有项目或按关键词模糊匹配搜索项目   | `--query`、`--json`                                                                                         |
+| `set-project` | 设置/更新/清空项目的显示名称、简介与备注 | `--project`、`--display-name`、`--description`、`--notes`、`--clear-description`、`--clear-notes`、`--json` |
+| `current`     | 所有项目或单项目的当前状态               | `--project`、`--json`                                                                                       |
+| `history`     | 全部或单个项目的历史，最新记录在前       | `--project`、`--since`、`--until`、`--limit`、`--offset`、`--json`                                          |
+| `at`          | 指定时间点及之前的最后状态               | `--project`、`--at`、`--json`                                                                               |
+| `export`      | 导出全部或单项目记录                     | `--project`、`--format json\|jsonl`                                                                         |
 
-全部六个 action 仍可使用 `status <action>` 的兼容形式，例如 `pmgr status export`。人类可读的多条结果按“项目、状态、发生时间、摘要”输出；为空时输出 `No entries found.`。`add`、`import`、`current`、`history`、`at` 支持 `--json`；`export` 由 `--format` 控制格式。
+全部 action 仍可使用 `status <action>` 的兼容形式，例如 `pmgr status projects`。人类可读的多条结果按项目及其最新状态输出；为空时输出 `No entries found.` 或 `No projects found.`。`add`、`import`、`current`、`projects`、`list`、`set-project`、`history`、`at` 支持 `--json`；`export` 由 `--format` 控制格式。
 
 导出内容不包含数据库内部的 `id` 和 `recordedAt`，可以直接重新导入。记录按时间从旧到新导出，从而在恢复时保留相同时间戳记录的先后关系：
 

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { readFileSync, realpathSync } from "node:fs";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
-import { addStatus, at, current, history, importStatuses, openLedger, parseTime, toPortableStatusEntry, ValidationError, } from "./index.js";
+import { addStatus, at, current, history, importStatuses, listProjects, openLedger, parseTime, setProjectMetadata, toPortableStatusEntry, ValidationError, } from "./index.js";
 const repeats = new Set(["next", "blocker", "decision", "tag"]);
 function parse(argv) {
     const command = [];
@@ -14,7 +14,9 @@ function parse(argv) {
             continue;
         }
         const key = token.slice(2);
-        if (key === "json") {
+        if (key === "json" ||
+            key === "clear-description" ||
+            key === "clear-notes") {
             if (flags[key] !== undefined)
                 throw new ValidationError(`--${key} may only be supplied once`);
             flags[key] = true;
@@ -39,6 +41,8 @@ const allowedFlags = new Map([
             "project",
             "status",
             "summary",
+            "description",
+            "notes",
             "progress",
             "blocker",
             "next",
@@ -52,6 +56,20 @@ const allowedFlags = new Map([
     ],
     ["import", new Set(["file", "json"])],
     ["current", new Set(["project", "json"])],
+    ["projects", new Set(["query", "json"])],
+    ["list", new Set(["query", "json"])],
+    [
+        "set-project",
+        new Set([
+            "project",
+            "display-name",
+            "description",
+            "notes",
+            "clear-description",
+            "clear-notes",
+            "json",
+        ]),
+    ],
     [
         "history",
         new Set(["project", "since", "until", "limit", "offset", "json"]),
@@ -64,7 +82,7 @@ function validateInvocation(command, flags) {
     const action = command[statusCommand ? 1 : 0];
     const allowed = typeof action === "string" ? allowedFlags.get(action) : undefined;
     if (typeof action !== "string" || !allowed)
-        throw new ValidationError("usage: pmgr <add|import|current|history|at|export> (or: pmgr status <action>)");
+        throw new ValidationError("usage: pmgr <add|import|current|projects|list|set-project|history|at|export> (or: pmgr status <action>)");
     const positional = command.slice(statusCommand ? 2 : 1);
     if (action === "import") {
         if (positional.length > 1)
@@ -110,6 +128,28 @@ function output(value, json, write) {
     else
         write(`${JSON.stringify(value, null, 2)}\n`);
 }
+function formatProjectOverview(item) {
+    const lines = [`${item.project}\t${item.displayName}`];
+    if (item.description)
+        lines.push(`  Description: ${item.description}`);
+    if (item.notes)
+        lines.push(`  Notes: ${item.notes}`);
+    if (item.latestStatus) {
+        lines.push(`  Latest Status: ${item.latestStatus.status}\t${item.latestStatus.occurredAt}\t${item.latestStatus.summary}`);
+    }
+    else {
+        lines.push(`  Latest Status: (none)`);
+    }
+    return lines.join("\n");
+}
+function outputProjects(items, json, write) {
+    if (json)
+        write(`${JSON.stringify(items)}\n`);
+    else if (items.length === 0)
+        write("No projects found.\n");
+    else
+        write(`${items.map(formatProjectOverview).join("\n")}\n`);
+}
 function imported(file) {
     if (!file)
         throw new ValidationError("import file is required");
@@ -141,9 +181,15 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
     const json = flags.json === true;
     try {
         switch (action) {
-            case "add":
+            case "add": {
+                const project = stringFlag(flags, "project", true);
+                const description = stringFlag(flags, "description");
+                const notes = stringFlag(flags, "notes");
+                if (description !== undefined || notes !== undefined) {
+                    setProjectMetadata(db, { project, description, notes });
+                }
                 output(addStatus(db, {
-                    project: stringFlag(flags, "project", true),
+                    project,
                     status: stringFlag(flags, "status", true),
                     summary: stringFlag(flags, "summary", true),
                     progress: stringFlag(flags, "progress"),
@@ -156,6 +202,7 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
                     externalRef: stringFlag(flags, "external-ref"),
                 }).entry, json, write);
                 break;
+            }
             case "import":
                 output(importStatuses(db, imported(stringFlag(flags, "file") ??
                     command[command[0] === "status" ? 2 : 1] ??
@@ -164,8 +211,41 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
             case "current":
                 output(current(db, stringFlag(flags, "project")), json, write);
                 break;
+            case "projects":
+            case "list":
+                outputProjects(listProjects(db, { query: stringFlag(flags, "query") }), json, write);
+                break;
+            case "set-project": {
+                const project = stringFlag(flags, "project", true);
+                const displayName = stringFlag(flags, "display-name");
+                let description = undefined;
+                if (flags["clear-description"] === true) {
+                    if (flags.description !== undefined)
+                        throw new ValidationError("cannot specify both --description and --clear-description");
+                    description = null;
+                }
+                else if (flags.description !== undefined) {
+                    description = stringFlag(flags, "description");
+                }
+                let notes = undefined;
+                if (flags["clear-notes"] === true) {
+                    if (flags.notes !== undefined)
+                        throw new ValidationError("cannot specify both --notes and --clear-notes");
+                    notes = null;
+                }
+                else if (flags.notes !== undefined) {
+                    notes = stringFlag(flags, "notes");
+                }
+                output(setProjectMetadata(db, {
+                    project,
+                    displayName,
+                    description,
+                    notes,
+                }), json, write);
+                break;
+            }
             case "history":
-                output(history(db, stringFlag(flags, "project", true), {
+                output(history(db, stringFlag(flags, "project"), {
                     since: stringFlag(flags, "since") &&
                         parseTime(stringFlag(flags, "since"), "since"),
                     until: stringFlag(flags, "until") &&

package/dist/db.d.ts

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import { type Source, type StatusEntry } from "./domain.js";
+import { type ProjectMetadata, type ProjectOverview, type Source, type StatusEntry } from "./domain.js";
 export type Ledger = Database.Database;
 export type InsertResult = {
     entry: StatusEntry;
@@ -13,6 +13,10 @@ export type HistoryOptions = {
 };
 export declare function databasePath(): string;
 export declare function openLedger(path?: string): Ledger;
+export declare function setProjectMetadata(db: Ledger, value: unknown): ProjectMetadata;
+export declare function listProjects(db: Ledger, options?: {
+    query?: string;
+}): ProjectOverview[];
 export declare function addStatus(db: Ledger, value: unknown, defaultSource?: Source): InsertResult;
 export declare function importStatuses(db: Ledger, values: unknown[]): InsertResult[];
 export declare function current(db: Ledger, project?: string): StatusEntry[];

package/dist/db.js

@@ -2,8 +2,8 @@ import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
-import { validateStatusEntry, ValidationError, } from "./domain.js";
-const migration = `
+import { validateProjectMetadataInput, validateStatusEntry, ValidationError, } from "./domain.js";
+const migration1 = `
 CREATE TABLE IF NOT EXISTS projects (
   id INTEGER PRIMARY KEY,
   slug TEXT NOT NULL UNIQUE,
@@ -27,6 +27,10 @@ CREATE TABLE IF NOT EXISTS status_entries (
 );
 CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries(project_id, occurred_at DESC, id DESC);
 `;
+const migration2 = `
+ALTER TABLE projects ADD COLUMN description TEXT;
+ALTER TABLE projects ADD COLUMN notes TEXT;
+`;
 export function databasePath() {
     return (process.env.PMGR_DB_PATH ||
         resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"));
@@ -39,9 +43,13 @@ export function openLedger(path = databasePath()) {
     db.exec("CREATE TABLE IF NOT EXISTS schema_migrations (version INTEGER PRIMARY KEY)");
     db.transaction(() => {
         if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 1").get()) {
-            db.exec(migration);
+            db.exec(migration1);
             db.prepare("INSERT INTO schema_migrations(version) VALUES (1)").run();
         }
+        if (!db.prepare("SELECT 1 FROM schema_migrations WHERE version = 2").get()) {
+            db.exec(migration2);
+            db.prepare("INSERT INTO schema_migrations(version) VALUES (2)").run();
+        }
     }).immediate();
     return db;
 }
@@ -67,6 +75,97 @@ function one(db, sql, ...params) {
     const row = db.prepare(sql).get(...params);
     return row && entryFromRow(row);
 }
+function upsertProjectMetadata(db, input) {
+    const existing = db
+        .prepare("SELECT 1 FROM projects WHERE slug = ?")
+        .get(input.project);
+    if (!existing) {
+        const now = new Date().toISOString();
+        db.prepare("INSERT INTO projects(slug, display_name, description, notes, created_at) VALUES (?, ?, ?, ?, ?)").run(input.project, input.displayName ?? input.project, input.description ?? null, input.notes ?? null, now);
+    }
+    else {
+        const updates = [];
+        const params = [];
+        if (input.displayName !== undefined) {
+            updates.push("display_name = ?");
+            params.push(input.displayName);
+        }
+        if (input.description !== undefined) {
+            updates.push("description = ?");
+            params.push(input.description);
+        }
+        if (input.notes !== undefined) {
+            updates.push("notes = ?");
+            params.push(input.notes);
+        }
+        if (updates.length > 0) {
+            params.push(input.project);
+            db.prepare(`UPDATE projects SET ${updates.join(", ")} WHERE slug = ?`).run(...params);
+        }
+    }
+}
+export function setProjectMetadata(db, value) {
+    const input = validateProjectMetadataInput(value);
+    return db.transaction(() => {
+        upsertProjectMetadata(db, input);
+        const row = db
+            .prepare("SELECT * FROM projects WHERE slug = ?")
+            .get(input.project);
+        return {
+            project: row.slug,
+            displayName: row.display_name,
+            ...(row.description ? { description: row.description } : {}),
+            ...(row.notes ? { notes: row.notes } : {}),
+            createdAt: row.created_at,
+        };
+    })();
+}
+export function listProjects(db, options = {}) {
+    const query = options.query?.trim().toLowerCase();
+    const projects = db
+        .prepare("SELECT * FROM projects ORDER BY slug ASC")
+        .all();
+    const latestStatuses = current(db);
+    const statusMap = new Map();
+    for (const entry of latestStatuses) {
+        statusMap.set(entry.project, entry);
+    }
+    const overviews = projects.map((row) => {
+        const slug = row.slug;
+        const latestStatus = statusMap.get(slug);
+        return {
+            project: slug,
+            displayName: row.display_name,
+            ...(row.description ? { description: row.description } : {}),
+            ...(row.notes ? { notes: row.notes } : {}),
+            createdAt: row.created_at,
+            ...(latestStatus ? { latestStatus } : {}),
+        };
+    });
+    if (!query)
+        return overviews;
+    return overviews.filter((overview) => {
+        if (overview.project.toLowerCase().includes(query))
+            return true;
+        if (overview.displayName.toLowerCase().includes(query))
+            return true;
+        if (overview.description?.toLowerCase().includes(query))
+            return true;
+        if (overview.notes?.toLowerCase().includes(query))
+            return true;
+        if (overview.latestStatus) {
+            if (overview.latestStatus.status.toLowerCase().includes(query))
+                return true;
+            if (overview.latestStatus.summary.toLowerCase().includes(query))
+                return true;
+            if (overview.latestStatus.progress?.toLowerCase().includes(query))
+                return true;
+            if (overview.latestStatus.tags.some((t) => t.toLowerCase().includes(query)))
+                return true;
+        }
+        return false;
+    });
+}
 export function addStatus(db, value, defaultSource = "human") {
     const input = validateStatusEntry(value, defaultSource);
     return db.transaction(() => addValidatedStatus(db, input))();
@@ -81,7 +180,7 @@ function addValidatedStatus(db, input) {
         }
     }
     const now = new Date().toISOString();
-    db.prepare("INSERT INTO projects(slug, display_name, created_at) VALUES (?, ?, ?) ON CONFLICT(slug) DO NOTHING").run(input.project, input.project, now);
+    upsertProjectMetadata(db, { project: input.project });
     const project = db
         .prepare("SELECT id FROM projects WHERE slug = ?")
         .get(input.project);

package/dist/domain.d.ts

@@ -2,6 +2,22 @@ export declare const statuses: readonly ["idea", "planned", "active", "blocked",
 export declare const sources: readonly ["human", "agent", "import"];
 export type ProjectStatus = (typeof statuses)[number];
 export type Source = (typeof sources)[number];
+export type ProjectMetadata = {
+    project: string;
+    displayName: string;
+    description?: string;
+    notes?: string;
+    createdAt: string;
+};
+export type ProjectOverview = ProjectMetadata & {
+    latestStatus?: StatusEntry;
+};
+export type ProjectMetadataInput = {
+    project: string;
+    displayName?: string;
+    description?: string | null;
+    notes?: string | null;
+};
 export type StatusEntryInput = {
     project: string;
     status: ProjectStatus;
@@ -26,5 +42,6 @@ export declare class ValidationError extends Error {
     constructor(message: string);
 }
 export declare function parseTime(value: unknown, field: string): string;
+export declare function validateProjectMetadataInput(value: unknown): ProjectMetadataInput;
 export declare function validateStatusEntry(value: unknown, defaultSource?: Source): StatusEntryInput & Required<Pick<StatusEntryInput, "occurredAt" | "source">>;
 export declare function toPortableStatusEntry(entry: StatusEntry): PortableStatusEntry;

package/dist/domain.js

@@ -21,6 +21,12 @@ const keys = new Set([
     "source",
     "externalRef",
 ]);
+const projectMetadataKeys = new Set([
+    "project",
+    "displayName",
+    "description",
+    "notes",
+]);
 const projectName = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 export class ValidationError extends Error {
     constructor(message) {
@@ -38,6 +44,20 @@ function text(value, field, required = false) {
         throw new ValidationError(`${field} must be at most 2000 characters`);
     return normalized;
 }
+function nullableText(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (value === null)
+        return null;
+    if (typeof value !== "string")
+        throw new ValidationError(`${field} must be a string or null`);
+    const normalized = value.trim();
+    if (normalized === "")
+        return null;
+    if (normalized.length > 2_000)
+        throw new ValidationError(`${field} must be at most 2000 characters`);
+    return normalized;
+}
 function textList(value, field) {
     if (value === undefined)
         return [];
@@ -53,6 +73,26 @@ export function parseTime(value, field) {
     }
     return new Date(value).toISOString();
 }
+export function validateProjectMetadataInput(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new ValidationError("project metadata must be an object");
+    const input = value;
+    for (const key of Object.keys(input))
+        if (!projectMetadataKeys.has(key))
+            throw new ValidationError(`unknown field: ${key}`);
+    const project = text(input.project, "project", true);
+    if (!projectName.test(project))
+        throw new ValidationError("project must use letters, numbers, dots, underscores, or hyphens");
+    const displayName = text(input.displayName, "displayName");
+    const description = nullableText(input.description, "description");
+    const notes = nullableText(input.notes, "notes");
+    return {
+        project,
+        ...(displayName !== undefined ? { displayName } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(notes !== undefined ? { notes } : {}),
+    };
+}
 export function validateStatusEntry(value, defaultSource = "human") {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new ValidationError("entry must be an object");
@@ -88,19 +128,20 @@ export function validateStatusEntry(value, defaultSource = "human") {
     };
 }
 export function toPortableStatusEntry(entry) {
-    return {
+    const result = {
         project: entry.project,
         status: entry.status,
         summary: entry.summary,
-        ...(entry.progress === undefined ? {} : { progress: entry.progress }),
         blockers: entry.blockers,
         nextSteps: entry.nextSteps,
         decisions: entry.decisions,
         tags: entry.tags,
         occurredAt: entry.occurredAt,
         source: entry.source,
-        ...(entry.externalRef === undefined
-            ? {}
-            : { externalRef: entry.externalRef }),
     };
+    if (entry.progress !== undefined)
+        result.progress = entry.progress;
+    if (entry.externalRef !== undefined)
+        result.externalRef = entry.externalRef;
+    return result;
 }

package/docs/architecture.md

@@ -36,8 +36,8 @@ The CLI accepts `pmgr <action>` for `add`, `import`, `current`, `history`, `at`,
 
 The database contains three structures:
 
-- `schema_migrations`: Applied migration versions.
-- `projects`: Project slug, display name, and creation time.
+- `schema_migrations`: Applied migration versions (1: base tables, 2: project description & notes columns).
+- `projects`: Project slug, display name, description, notes, and creation time.
 - `status_entries`: Immutable status snapshots and their project foreign keys.
 
 Key `status_entries` fields:
@@ -55,7 +55,7 @@ The `project_id, occurred_at DESC, id DESC` index supports current-status and hi
 
 ## Initialization and migrations
 
-After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migration 1 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
+After opening the database, `openLedger()` enables foreign keys, creates the migration table, and checks for and applies migrations 1 and 2 within a `BEGIN IMMEDIATE` transaction. The immediate transaction prevents migration checks and writes from interleaving when several local processes open the database for the first time at once.
 
 The database path is read from `PMGR_DB_PATH` first; otherwise, it uses the absolute path `~/.local/share/project-mgr/project-mgr.sqlite`, resolved from the current user's home directory. Non-memory databases create their parent directory automatically.