@hasna/knowledge 0.2.3 → 0.2.5

package/README.md

@@ -1,12 +1,15 @@
 # open-knowledge
 
-> Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions.
+> Agent-friendly local knowledge CLI/MCP with JSON output, project workspaces, durable artifacts, and safe destructive actions.
 
 [![npm version](https://img.shields.io/npm/v/@hasna/knowledge)](https://npm.im/@hasna/knowledge)
 [![license](https://img.shields.io/npm/l/@hasna/knowledge)](LICENSE)
 [![build](https://img.shields.io/github/actions/workflow/status/hasna/knowledge/ci.yml)](.github/workflows/ci.yml)
 
-A flat key-value knowledge store designed for AI agents. Stores notes with titles, content, source URLs, and tags. Works with Bun and Node.js.
+`open-knowledge` is evolving from a flat note store into a local-first knowledge
+engine for AI agents. It stores simple knowledge items today, creates a Hasna
+project workspace under `.hasna/apps/knowledge`, initializes a versioned
+`knowledge.db`, writes generated wiki artifacts, and exposes a stdio MCP server.
 
 ## Install
 
@@ -50,6 +53,18 @@ open-knowledge delete --id <id> --yes
 
 # Export all notes as JSONL
 open-knowledge export --format jsonl
+
+# Show resolved workspace paths
+open-knowledge paths --scope project --json
+
+# Initialize the project SQLite catalog
+open-knowledge db init --scope project
+
+# Initialize scalable wiki/schema/index/log artifacts
+open-knowledge wiki init --scope project
+
+# Ingest an open-files source manifest into the project SQLite catalog
+open-knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
 ```
 
 ## Commands
@@ -94,6 +109,25 @@ Update an existing item.
 | `--url <url>` | New source URL |
 | `-t, --tag <tag>` | Add a tag |
 
+### archive / restore
+```bash
+open-knowledge archive --id <id>
+open-knowledge restore --id <id>
+```
+Archive hides an item from default `list` output without deleting it.
+
+### upsert
+```bash
+open-knowledge upsert [title] [content] [--id <id>] [--title <title>] [--content <content>]
+```
+Create or update an item by ID.
+
+### untag
+```bash
+open-knowledge untag --id <id> -t <tag>
+```
+Remove one tag from an item.
+
 ### delete
 ```bash
 open-knowledge delete|rm --id <id> --yes
@@ -106,6 +140,37 @@ open-knowledge export [--format jsonl]
 ```
 Export all items. Use `--format jsonl` for newline-delimited JSON.
 
+### paths
+```bash
+open-knowledge paths [--scope global|project|local] [--json]
+```
+Show the resolved Hasna app workspace, JSON compatibility store, SQLite path,
+artifact directories, and config.
+
+### db
+```bash
+open-knowledge db init [--scope project]
+open-knowledge db stats [--scope project]
+```
+Initialize or inspect the versioned SQLite catalog at
+`.hasna/apps/knowledge/knowledge.db`.
+
+### wiki
+```bash
+open-knowledge wiki init [--scope project]
+```
+Create starter generated-knowledge artifacts through the artifact store:
+`schemas/v1.md`, `indexes/root.md`, `wiki/README.md`, and a dated JSONL log
+partition.
+
+### ingest
+```bash
+open-knowledge ingest manifest <file|s3://bucket/key> [--scope project] [--json]
+```
+Import an open-files JSON or JSONL source manifest into `knowledge.db`. This
+upserts sources and source revisions, stores hash/MIME/status/permission
+metadata, and chunks embedded extracted text when the manifest includes it.
+
 ### help
 ```bash
 open-knowledge help [command]
@@ -117,14 +182,42 @@ open-knowledge help [command]
 |------|-------------|
 | `--json` | Output raw JSON |
 | `--store <path>` | Override store path |
+| `--scope global\|project\|local` | Select global Hasna app workspace or project workspace |
 | `--version, -v` | Show version |
 | `--help, -h` | Show help |
 
 ## Store Location
 
-Default store: `~/.open-knowledge/db.json`
+Default global compatibility store: `~/.hasna/apps/knowledge/db.json`
+
+Project workspace: `.hasna/apps/knowledge/`
+
+The legacy `~/.open-knowledge/db.json` store is migrated into the new global
+Hasna app path on first use if the new store does not exist. Override item-store
+location with `--store <path>`.
+
+## MCP Server
+
+```bash
+open-knowledge-mcp
+```
+
+The MCP server exposes item tools (`ok_add`, `ok_list`, `ok_get`, `ok_update`,
+`ok_delete`, `ok_archive`, `ok_restore`, `ok_upsert`, `ok_untag`,
+`ok_bulk_delete`, `ok_prune`, `ok_dedupe`, `ok_stats`, `ok_export`,
+`ok_import`, `ok_batch`), workspace inspection (`ok_paths`), and source-ref
+parsing (`ok_parse_source_ref`).
+
+## Source And Artifact Boundary
+
+Raw files should be stored and resolved through `open-files`. `open-knowledge`
+stores source references such as `open-files://file/<id>`,
+`open-files://file/<id>/revision/<revision_id>`, `s3://...`, `file://...`,
+and `https://...`, plus citations, chunks, generated wiki pages, indexes,
+logs, runs, and search metadata.
 
-Override with `--store <path>` or set `OPEN_KNOWLEDGE_STORE` env var.
+Generated knowledge artifacts can be stored locally under
+`.hasna/apps/knowledge/artifacts` or through the S3 artifact-store adapter.
 
 ## JSON Output