project-mgr 0.1.1 → 0.1.3

package/.env_sample

@@ -1,5 +1,7 @@
-# SQLite database path. Relative paths are resolved from the current directory.
-PMGR_DB_PATH=./data/project-mgr.sqlite
+# Optional SQLite database override. When unset, the database is stored at
+# ~/.local/share/project-mgr/project-mgr.sqlite.
+# Use a literal absolute path here; .env files do not expand ~ or $HOME.
+# PMGR_DB_PATH=/absolute/path/to/project-mgr.sqlite
 
 # For isolated manual testing, use a separate database instead:
-# PMGR_DB_PATH=./data/manual-test.sqlite
+# PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+## 0.1.3 - 2026-08-03
+
+### Added
+
+- Packaged the `project-mgr-status` Agent Skill for status ledger operations.
+
+### Fixed
+
+- Made the CLI run through npm-created `pmgr` symlinks and corrected the no-install examples.
+
+## 0.1.2 - 2026-08-03
+
+### Changed
+
+- Moved the default database from the command's working directory to the stable per-user path `~/.local/share/project-mgr/project-mgr.sqlite`.
+
 ## 0.1.1 - 2026-08-03
 
 ### Changed

package/README.md

@@ -4,7 +4,7 @@
 
 `project-mgr` is a local-first, append-only ledger for project status. It stores progress, blockers, decisions, and next steps as timestamped status snapshots, so people and AI agents can quickly inspect each project's current state, complete history, or state at a particular time.
 
-The first release provides only a local CLI and SQLite. It has no HTTP API, long-running service, or agent skills. Data stays on the local machine and requires no account or cloud service.
+The first release provides a local CLI, SQLite, and an optional Agent Skill. It has no HTTP API or long-running service. Data stays on the local machine and requires no account or cloud service.
 
 ## Run from npm
 
@@ -13,7 +13,7 @@ Requires Node.js 22+.
 Run without installing:
 
 ```bash
-npx --yes project-mgr current
+npx --yes --package project-mgr pmgr current
 ```
 
 Or install the CLI globally:
@@ -23,12 +23,28 @@ npm install --global project-mgr
 pmgr current
 ```
 
-The database defaults to `./data/project-mgr.sqlite` in the current working directory. Set `PMGR_DB_PATH` to use another location:
+The database defaults to `~/.local/share/project-mgr/project-mgr.sqlite`, regardless of the directory where `pmgr` is executed. The CLI resolves this to an absolute path using the current user's home directory and creates the parent directory automatically.
+
+Set `PMGR_DB_PATH` to use another location:
+
+```bash
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes --package project-mgr pmgr current
+```
+
+## Install the Agent Skill
+
+The repository includes `skills/project-mgr-status`, which guides compatible AI agents to add, import, query, and export status records. Install it with the [skills CLI](https://skills.sh/docs/cli):
 
 ```bash
-PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+npx skills add deanplus/project-manager
 ```
 
+The installer detects supported agents and asks where to install the skill. No separate `project-mgr` installation is required: the skill runs the CLI through `npx`. Restart or reload the selected agent after installation.
+
+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.
+
+Then ask the agent, for example: `Use project-mgr-status to add an active status for project-mgr after checking its current status.`
+
 ## Build from source
 
 Requires Node.js 22+ and pnpm 10.30.2.
@@ -53,26 +69,26 @@ During development, run the TypeScript CLI directly:
 pnpm pmgr current
 ```
 
-The default configuration in `.env_sample` is:
+The default database path is:
 
-```dotenv
-PMGR_DB_PATH=./data/project-mgr.sqlite
+```text
+~/.local/share/project-mgr/project-mgr.sqlite
 ```
 
-Set `PMGR_DB_PATH` in `.env` to use another location, or override it for one command:
+`PMGR_DB_PATH` is optional in `.env_sample`. Set it in `.env` to use another location, or override it for one command:
 
 ```bash
 PMGR_DB_PATH=/absolute/path/projects.sqlite pnpm start current
 ```
 
-Relative paths are resolved from the working directory of the command. When `pnpm start ...` runs from this project's root, the default database is `./data/project-mgr.sqlite`. It is created automatically when the first valid command runs.
+Use a literal absolute path in `.env`; `.env` files do not expand `~` or `$HOME`. The database is created automatically when the first valid command runs.
 
 ### Use an isolated test database
 
 For manual testing, set a persistent path in `.env` that is separate from production data:
 
 ```dotenv
-PMGR_DB_PATH=./data/manual-test.sqlite
+PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite
 ```
 
 Then run commands normally:
@@ -88,7 +104,7 @@ pnpm start history --project test-project
 
 Project keys must match exactly: a record added to `test-project` is not part of `project-mgr` history. Empty human-readable list queries print `No entries found.`; with `--json`, they print `[]`.
 
-`data/` is ignored by Git, so test data is not committed. Delete `data/manual-test.sqlite` when it is no longer needed.
+Delete `/tmp/project-mgr-manual-test.sqlite` when it is no longer needed.
 
 Automated tests use an in-memory database or SQLite files in the system temporary directory; they do not read or write the default database. `PMGR_DB_PATH=:memory:` also works for one command, but each CLI command runs in a separate process and its data disappears when the command exits, so it is not suitable for consecutive manual tests.
 
@@ -189,7 +205,7 @@ Exports omit the database-internal `id` and `recordedAt` fields and can be impor
 ```bash
 pnpm start export --format jsonl > project-statuses.jsonl
 
-PMGR_DB_PATH=./data/restored.sqlite \
+PMGR_DB_PATH=/tmp/project-mgr-restored.sqlite \
   pnpm start import project-statuses.jsonl
 ```
 

package/README_CN.md

@@ -4,7 +4,7 @@
 
 `project-mgr` 是一个本地优先、只追加的项目状态账本。它把项目进展、阻塞、决策和下一步保存为带时间的状态快照，让个人或 AI Agent 能快速查询每个项目的当前状态、完整历史以及某个时间点的状态。
 
-首版只提供本地 CLI 和 SQLite，不包含 HTTP API、常驻服务或 Agent Skills。数据默认保存在本机，无需账号或云服务。
+首版提供本地 CLI、SQLite 和可选的 Agent Skill，不包含 HTTP API 或常驻服务。数据默认保存在本机，无需账号或云服务。
 
 ## 从 npm 运行
 
@@ -13,7 +13,7 @@
 无需安装即可运行：
 
 ```bash
-npx --yes project-mgr current
+npx --yes --package project-mgr pmgr current
 ```
 
 也可以全局安装 CLI：
@@ -23,12 +23,28 @@ npm install --global project-mgr
 pmgr current
 ```
 
-数据库默认位于当前工作目录下的 `./data/project-mgr.sqlite`。通过 `PMGR_DB_PATH` 指定其他位置：
+无论在哪个目录执行 `pmgr`，数据库都默认位于 `~/.local/share/project-mgr/project-mgr.sqlite`。CLI 会根据当前用户的主目录将其解析为绝对路径，并自动创建父目录。
+
+通过 `PMGR_DB_PATH` 指定其他位置：
+
+```bash
+PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes --package project-mgr pmgr current
+```
+
+## 安装 Agent Skill
+
+仓库包含 `skills/project-mgr-status`，用于指导兼容 Skills 的 AI Agent 新增、导入、查询和导出项目状态记录。通过 [skills CLI](https://skills.sh/docs/cli) 安装：
 
 ```bash
-PMGR_DB_PATH=/absolute/path/projects.sqlite npx --yes project-mgr current
+npx skills add deanplus/project-manager
 ```
 
+安装器会检测支持的 Agent，并询问安装目标。无需单独安装 `project-mgr`：该 Skill 会通过 `npx` 运行 CLI。安装后重启或重新加载所选 Agent。
+
+该 Skill 与 CLI 使用相同的 `PMGR_DB_PATH` 规则：默认使用 `~/.local/share/project-mgr/project-mgr.sqlite`；如需使用其他账本，请设置绝对路径。手工或探索性操作请使用独立数据库，例如 `PMGR_DB_PATH=/tmp/project-mgr-skill-test.sqlite`，避免写入默认账本。
+
+随后可向 Agent 提出，例如：`使用 project-mgr-status，在查询当前状态后为 project-mgr 新增一条 active 状态。`
+
 ## 从源码构建
 
 需要 Node.js 22+ 和 pnpm 10.30.2。
@@ -53,26 +69,26 @@ pnpm start current
 pnpm pmgr current
 ```
 
-默认配置位于 `.env_sample`：
+默认数据库路径是：
 
-```dotenv
-PMGR_DB_PATH=./data/project-mgr.sqlite
+```text
+~/.local/share/project-mgr/project-mgr.sqlite
 ```
 
-通过 `.env` 中的 `PMGR_DB_PATH` 指定其他位置，也可以为单条命令临时覆盖：
+`.env_sample` 中的 `PMGR_DB_PATH` 是可选配置。可以在 `.env` 中指定其他位置，也可以为单条命令临时覆盖：
 
 ```bash
 PMGR_DB_PATH=/absolute/path/projects.sqlite pnpm start current
 ```
 
-路径基于启动命令的当前工作目录计算。从本项目根目录执行 `pnpm start ...` 时，默认位置就是 `./data/project-mgr.sqlite`。数据库会在第一次执行有效命令时自动创建。
+在 `.env` 中应填写字面量绝对路径；`.env` 文件不会展开 `~` 或 `$HOME`。数据库会在第一次执行有效命令时自动创建。
 
 ### 使用独立测试数据库
 
 手工测试时，建议在 `.env` 中固定设置一个与正式数据分离的路径：
 
 ```dotenv
-PMGR_DB_PATH=./data/manual-test.sqlite
+PMGR_DB_PATH=/tmp/project-mgr-manual-test.sqlite
 ```
 
 随后正常执行命令：
@@ -88,7 +104,7 @@ pnpm start history --project test-project
 
 项目键必须完全一致：写入 `test-project` 的记录不会出现在 `project-mgr` 的历史中。人类可读的空列表查询会输出 `No entries found.`；使用 `--json` 时则输出 `[]`。
 
-`data/` 已加入 Git ignore，测试数据不会进入版本库。不需要保留时，可以删除 `data/manual-test.sqlite`。
+不需要保留时，可以删除 `/tmp/project-mgr-manual-test.sqlite`。
 
 自动化测试会使用内存数据库或系统临时目录中的 SQLite 文件，不会读写默认数据库。`PMGR_DB_PATH=:memory:` 也可用于单条命令，但每个 CLI 命令都是独立进程，命令结束后数据就会消失，不适合连续手工测试。
 
@@ -189,7 +205,7 @@ pnpm start import --file statuses.jsonl --json
 ```bash
 pnpm start export --format jsonl > project-statuses.jsonl
 
-PMGR_DB_PATH=./data/restored.sqlite \
+PMGR_DB_PATH=/tmp/project-mgr-restored.sqlite \
   pnpm start import project-statuses.jsonl
 ```
 

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+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";
 const repeats = new Set(["next", "blocker", "decision", "tag"]);
@@ -201,7 +201,7 @@ export function run(argv, write = process.stdout.write.bind(process.stdout)) {
 }
 /* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
 if (process.argv[1] &&
-    import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
     try {
         run(process.argv.slice(2));
     }

package/dist/db.js

@@ -1,5 +1,6 @@
 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 = `
@@ -28,7 +29,7 @@ CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries
 `;
 export function databasePath() {
     return (process.env.PMGR_DB_PATH ||
-        resolve(process.cwd(), "data", "project-mgr.sqlite"));
+        resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"));
 }
 export function openLedger(path = databasePath()) {
     if (path !== ":memory:")

package/docs/architecture.md

@@ -57,7 +57,7 @@ The `project_id, occurred_at DESC, id DESC` index supports current-status and hi
 
 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.
 
-The database path is read from `PMGR_DB_PATH` first; otherwise, it uses `data/project-mgr.sqlite` in the process working directory. Non-memory databases create their parent directory automatically.
+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.
 
 ## Write flow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-mgr",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local-first append-only project status ledger",
   "type": "module",
   "bin": {

package/skills/project-mgr-status/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: project-mgr-status
+description: Manage project status with the local-first project-mgr CLI. Use when an AI agent needs to add an append-only project update, import status records, query current or historical project state, or export a status ledger.
+---
+
+# Project Mgr Status
+
+Use `npx --yes --package project-mgr pmgr`. In a source checkout, use `pnpm pmgr` instead.
+
+## Database safety
+
+- Read `PMGR_DB_PATH` before operating. If unset, the CLI uses `~/.local/share/project-mgr/project-mgr.sqlite`.
+- For exploratory or test work, set `PMGR_DB_PATH` to a dedicated absolute SQLite path for every command. Do not use `:memory:` when more than one CLI invocation must share data.
+- Query before writing. `add` appends a snapshot; it does not edit the previous one.
+- Set `--source agent` for agent-authored updates. Use `--external-ref` only when a stable idempotency key is available.
+
+## Operations
+
+Prefer `--json` for data that must be interpreted or reported programmatically.
+
+```bash
+# Add an agent-authored status snapshot.
+npx --yes --package project-mgr pmgr add --project my-project --status active --summary "Implemented the CLI" \
+  --progress "Tests pass" --next "Publish the package" --source agent --json
+
+# Query current state, history, or state at a time.
+npx --yes --package project-mgr pmgr current --project my-project --json
+npx --yes --package project-mgr pmgr history --project my-project --limit 20 --json
+npx --yes --package project-mgr pmgr at --project my-project --at 2026-08-03T12:00:00+08:00 --json
+
+# Import validated JSON/JSONL, or export portable records.
+npx --yes --package project-mgr pmgr import statuses.jsonl --json
+npx --yes --package project-mgr pmgr export --project my-project --format jsonl > statuses.jsonl
+```
+
+Use `PMGR_DB_PATH=/absolute/path/test.sqlite npx --yes --package project-mgr pmgr ...` to isolate a manual test database. Import validates the entire batch before one transaction writes it; export output can be imported directly.

package/skills/project-mgr-status/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Project Status Ledger"
+  short_description: "Manage local project status records safely"
+  default_prompt: "Use $project-mgr-status to add and inspect this project status."

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename } from "node:path";
 import { pathToFileURL } from "node:url";
 import {
   addStatus,
@@ -260,7 +260,7 @@ export function run(
 /* c8 ignore start -- process entry glue is covered by the CLI integration tests through run(). */
 if (
   process.argv[1] &&
-  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+  import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href
 ) {
   try {
     run(process.argv.slice(2));

package/src/db.ts

@@ -1,5 +1,6 @@
 import Database from "better-sqlite3";
 import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import {
   type Source,
@@ -46,7 +47,7 @@ CREATE INDEX IF NOT EXISTS idx_status_entries_project_occurred ON status_entries
 export function databasePath(): string {
   return (
     process.env.PMGR_DB_PATH ||
-    resolve(process.cwd(), "data", "project-mgr.sqlite")
+    resolve(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite")
   );
 }
 

package/test/core.test.ts

@@ -1,8 +1,10 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
+import { fileURLToPath } from "node:url";
 import { run } from "../src/cli.js";
 import {
   addStatus,
@@ -171,7 +173,7 @@ test("import validates before transaction and default source is import", () => {
   db.close();
 });
 
-test("database path uses environment override and file migration creates parent directory", () => {
+test("database path has a stable default and environment override creates its parent directory", () => {
   const directory = mkdtempSync(join(tmpdir(), "pmgr-"));
   const previous = process.env.PMGR_DB_PATH;
   process.env.PMGR_DB_PATH = join(directory, "nested", "ledger.sqlite");
@@ -180,7 +182,30 @@ test("database path uses environment override and file migration creates parent
   db.close();
   if (previous === undefined) delete process.env.PMGR_DB_PATH;
   else process.env.PMGR_DB_PATH = previous;
-  assert.match(databasePath(), /data\/project-mgr\.sqlite$/);
+  assert.equal(
+    databasePath(),
+    join(homedir(), ".local", "share", "project-mgr", "project-mgr.sqlite"),
+  );
+  rmSync(directory, { recursive: true, force: true });
+});
+
+test("CLI runs through a package-style symlink", () => {
+  const directory = mkdtempSync(join(tmpdir(), "pmgr-bin-"));
+  const executable = join(directory, "pmgr");
+  symlinkSync(
+    fileURLToPath(new URL("../src/cli.ts", import.meta.url)),
+    executable,
+  );
+  const result = spawnSync(
+    process.execPath,
+    ["--import", "tsx", executable, "current", "--json"],
+    {
+      encoding: "utf8",
+      env: { ...process.env, PMGR_DB_PATH: ":memory:" },
+    },
+  );
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(result.stdout, "[]\n");
   rmSync(directory, { recursive: true, force: true });
 });