@hasna/knowledge 0.2.7 → 0.2.9

package/README.md

@@ -66,9 +66,15 @@ 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
 
+# Ingest one read-only source ref directly
+open-knowledge ingest source file:///absolute/path/to/handbook.md --purpose knowledge_index --scope project --json
+
 # Consume open-files change events and invalidate stale source chunks
 open-knowledge reindex outbox ./open-files-outbox.jsonl --scope project --json
 
+# Resolve indexed source text and citation evidence through the read-only source boundary
+open-knowledge source resolve open-files://file/f_123/revision/rev_456 --scope project --json
+
 # Inspect local safety policy and approvals
 open-knowledge safety status --scope project --json
 ```
@@ -169,14 +175,32 @@ Create starter generated-knowledge artifacts through the artifact store:
 `schemas/v1.md`, `indexes/root.md`, `wiki/README.md`, and a dated JSONL log
 partition.
 
+### source
+```bash
+open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope project] [--json]
+```
+Resolve an indexed source through the read-only open-files boundary. The result
+returns source metadata, permissions, the selected revision, derived chunk text,
+and citation evidence. It does not expose raw file bytes or storage credentials;
+raw source retrieval remains owned by `open-files`.
+
 ### ingest
 ```bash
 open-knowledge ingest manifest <file|s3://bucket/key> [--scope project] [--json]
+open-knowledge ingest source <source-ref> [--purpose knowledge_index] [--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.
 
+`ingest source` accepts `open-files://`, `file://`, `s3://`, and `https://`
+refs. It reads source content through a read-only boundary, redacts known
+secrets before storage, records hashes/revisions, and stores only derived chunks
+and citation spans. Web and S3 reads remain opt-in through the safety policy.
+For `open-files://` refs, the source must already be present in the local
+knowledge catalog through a manifest or extracted-text ref until the open-files
+resolver API lands.
+
 ### reindex
 ```bash
 open-knowledge reindex outbox <file|s3://bucket/key> [--scope project] [--json]
@@ -232,7 +256,7 @@ 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`).
+parsing/resolution (`ok_parse_source_ref`, `ok_resolve_source`).
 
 ## Source And Artifact Boundary
 
@@ -242,6 +266,16 @@ stores source references such as `open-files://file/<id>`,
 and `https://...`, plus citations, chunks, generated wiki pages, indexes,
 logs, runs, and search metadata.
 
+`open-knowledge source resolve` and the MCP `ok_resolve_source` tool resolve
+only the indexed, derived knowledge catalog. The resolver enforces read-only
+purpose labels from source permissions, returns chunk citation evidence, writes
+an audit event, and keeps bytes/storage credentials inside `open-files`.
+
+`open-knowledge ingest source` can also build derived chunks from an allowed
+source ref. It does not copy raw files into the knowledge workspace; local file,
+S3, web, and open-files inputs are converted into redacted chunks with offsets,
+hashes, revision metadata, and FTS rows.
+
 Generated knowledge artifacts can be stored locally under
 `.hasna/apps/knowledge/artifacts` or through the S3 artifact-store adapter.