@hasna/knowledge 0.2.25 → 0.2.27

package/docs/architecture/ai-native-knowledge-base.md

@@ -159,6 +159,30 @@ s3://<knowledge-bucket>/<org>/<project>/knowledge/
   wiki/
 ```
 
+Hasna XYZ production uses the canonical open-source knowledge bucket and app
+path-compatible prefix:
+
+```text
+s3://hasna-xyz-opensource-knowledge-prod/.hasna/apps/knowledge/
+```
+
+The app config can be materialized with:
+
+```bash
+open-knowledge setup --mode hosted --canonical-hasna-xyz --scope project --json
+```
+
+The canonical metadata-only secret paths are:
+
+```text
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/s3
+```
+
+`hasna/xyz/opensource/knowledge/prod/rds` is reserved for a future hosted
+runtime database if the wrapper provisions one.
+
 Raw files still route through `open-files`. Knowledge S3 storage is for derived
 artifacts such as wiki pages, index shards, schema versions, logs, exports, and
 run outputs.

package/docs/architecture/hosted-wrapper-responsibilities.md

@@ -86,6 +86,14 @@ The OSS package may know a storage contract, bucket name, prefix, region, and
 profile. It must not contain tenant secret values, connector credentials, RDS
 passwords, hosted KMS key material, or privileged AWS role assumptions.
 
+For Hasna XYZ production, the OSS contract names
+`hasna-xyz-opensource-knowledge-prod` and prefix
+`.hasna/apps/knowledge/`, plus metadata-only secret paths under
+`hasna/xyz/opensource/knowledge/prod/{env,aws,s3}`. Hosted code is responsible
+for resolving those secrets, assuming AWS roles, enforcing tenant prefixes, and
+provisioning `hasna/xyz/opensource/knowledge/prod/rds` only if a hosted runtime
+database is introduced.
+
 Generated artifacts are safe to sync remotely only when they remain derived:
 wiki pages, index shards, schema files, logs, exports, run payloads, embeddings,
 and citation metadata. Raw source bytes stay in `open-files`.

package/docs/canonical-secrets-bootstrap-2026-06-08.md

@@ -0,0 +1,127 @@
+# Canonical Secrets Bootstrap Evidence: 2026-06-08
+
+Scope: canonical Hasna XYZ app secret paths in account `hasna-xyz-infra`
+(`789877399345`), region `us-east-1`, mirrored into the local `spark02`
+`secrets` vault.
+
+This note records names and migration intent only. It intentionally does not
+include secret payloads, passwords, API keys, connection strings, or `.env`
+contents.
+
+## Ownership Rule
+
+App-owned runtime/config secrets use:
+
+```txt
+hasna/xyz/{app_type}/{app}/prod/{component}
+```
+
+Shared infra/admin pointers use an infra-owned path:
+
+```txt
+hasna/xyz/infra/{resource_group}/prod/{component}/{role}
+```
+
+Legacy master credentials copied for migration are suffixed with
+`legacy-master`. They are deprecation inputs for migration jobs, not the clean
+runtime secret names new app code should read.
+
+## Open Files
+
+Created or verified in AWS Secrets Manager and the local vault:
+
+```txt
+hasna/xyz/opensource/files/prod/env
+hasna/xyz/opensource/files/prod/aws
+hasna/xyz/opensource/files/prod/s3
+hasna/xyz/opensource/files/prod/rds
+```
+
+Meaning:
+
+- `env`: app environment configuration.
+- `aws`: AWS account/profile/region and related app config metadata.
+- `s3`: canonical app storage bucket metadata for
+  `hasna-xyz-opensource-files-prod`.
+- `rds`: app runtime database connection fields for database `files` and role
+  `files_app`.
+
+The `aws` and `s3` entries are metadata-only. They do not contain access keys or
+tokens.
+
+## Open Knowledge
+
+Created or verified in AWS Secrets Manager and the local vault:
+
+```txt
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/s3
+```
+
+Meaning:
+
+- `env`: open-knowledge production app config metadata.
+- `aws`: AWS account/profile/region and related app config metadata.
+- `s3`: canonical app storage bucket metadata for
+  `hasna-xyz-opensource-knowledge-prod`.
+
+No `hasna/xyz/opensource/knowledge/prod/rds` secret was created in this pass.
+The OSS package is local-first and currently uses SQLite for local knowledge
+state. If a hosted wrapper later provisions an app database, the app-owned
+runtime secret should use:
+
+```txt
+hasna/xyz/opensource/knowledge/prod/rds
+```
+
+## Legacy Secret Mapping
+
+Mapped legacy AWS Secrets Manager names to canonical ownership paths:
+
+| Legacy name | Canonical path | Use |
+| --- | --- | --- |
+| `prod/microservice/rds/master` | `hasna/xyz/opensource/microservices/prod/rds/legacy-master` | Migration-only legacy master alias. |
+| `prod/connect/rds/master` | `hasna/xyz/opensource/connectors/prod/rds/legacy-master` | Migration-only legacy master alias. |
+| `internalapps/prod/rds/master` | `hasna/xyz/infra/apps/prod/postgres/legacy-internalapps-master` | Migration-only legacy shared/admin alias. |
+| `internalapps/prod/iapp-news/env` | `hasna/xyz/internalapp/news/prod/env` | Canonical app env path for internalapp `news`. |
+
+The three RDS aliases preserve old master credential payloads under explicit
+legacy names so migration jobs can read them without relying on noncanonical
+paths. They should not be used as the final runtime credentials for new app
+code. Clean app runtime database credentials should be provisioned under
+app-owned paths such as:
+
+```txt
+hasna/xyz/opensource/files/prod/rds
+hasna/xyz/internalapp/news/prod/rds
+```
+
+The shared canonical Postgres admin pointer remains:
+
+```txt
+hasna/xyz/infra/apps/prod/postgres/master
+```
+
+## Verification
+
+AWS Secrets Manager name-only verification returned these canonical entries:
+
+```txt
+hasna/xyz/infra/apps/prod/postgres/legacy-internalapps-master
+hasna/xyz/infra/apps/prod/postgres/master
+hasna/xyz/internalapp/news/prod/env
+hasna/xyz/opensource/connectors/prod/rds/legacy-master
+hasna/xyz/opensource/files/prod/aws
+hasna/xyz/opensource/files/prod/env
+hasna/xyz/opensource/files/prod/rds
+hasna/xyz/opensource/files/prod/s3
+hasna/xyz/opensource/knowledge/prod/aws
+hasna/xyz/opensource/knowledge/prod/env
+hasna/xyz/opensource/knowledge/prod/s3
+hasna/xyz/opensource/microservices/prod/rds/legacy-master
+```
+
+Local `secrets list` verification returned the same names with redacted values.
+
+No secret values were printed during creation or verification.

package/docs/examples/company-wiki-workflow.md

@@ -0,0 +1,176 @@
+# Company Wiki Workflow
+
+This workflow shows how to use `open-knowledge` as an AI-native company wiki
+layer over source files owned by `open-files`.
+
+## 1. Initialize The Project Workspace
+
+```bash
+open-knowledge paths --scope project --json
+open-knowledge db init --scope project --json
+open-knowledge wiki init --scope project --json
+```
+
+Project state is created under:
+
+```text
+.hasna/apps/knowledge/
+  config.json
+  knowledge.db
+  artifacts/
+  indexes/
+  logs/
+  runs/
+  schemas/
+  wiki/
+```
+
+## 2. Import Source Metadata From Open-Files
+
+Use an `open-files` manifest with source refs, revisions, permissions, hashes,
+and extracted text:
+
+```json
+{
+  "source_ref": "open-files://file/file_handbook/revision/rev_20260608",
+  "file_id": "file_handbook",
+  "path": "Handbook/Policy.md",
+  "name": "Policy.md",
+  "mime": "text/markdown",
+  "hash": "sha256:...",
+  "status": "active",
+  "permissions": {
+    "mode": "read_only",
+    "allowed_purposes": ["knowledge_answer", "knowledge_index"]
+  },
+  "extracted_text": "Policy text..."
+}
+```
+
+Then ingest it:
+
+```bash
+open-knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
+```
+
+The knowledge app stores source refs, revisions, redacted chunks, offsets, and
+citations. It does not store raw source bytes or connector credentials.
+
+## 3. Search And Build Context
+
+Run local keyword/catalog search first:
+
+```bash
+open-knowledge search "expense policy" --scope project --json
+```
+
+Add deterministic local semantic indexing for a smoke test:
+
+```bash
+open-knowledge embeddings index --scope project --fake --dimensions 8 --json
+open-knowledge search "expense policy" --scope project --semantic --fake --dimensions 8 --json
+```
+
+Ask for an agent-ready context pack:
+
+```bash
+open-knowledge search "expense policy" --scope project --context --json
+```
+
+## 4. Answer With Citations
+
+Create a local citation draft:
+
+```bash
+knowledge "How do we approve expenses?" --scope project --json
+```
+
+Use provider generation explicitly:
+
+```bash
+OPENAI_API_KEY=... \
+knowledge "How do we approve expenses?" \
+  --scope project \
+  --generate \
+  --model openai:gpt-5-mini \
+  --json
+```
+
+Every prompt run records `runs`, `run_events`, provider/model metadata, usage,
+citations, and proposed wiki updates.
+
+## 5. Compile Durable Wiki Pages
+
+Compile a cited page from indexed chunks:
+
+```bash
+open-knowledge wiki compile "expense policy" \
+  --title "Expense Policy" \
+  --scope project \
+  --json
+```
+
+File an approved answer note:
+
+```bash
+open-knowledge wiki file-answer "How do we approve expenses?" \
+  --content "Use manager approval and cite the policy source." \
+  --approve-write \
+  --scope project \
+  --json
+```
+
+Lint the generated wiki:
+
+```bash
+open-knowledge wiki lint --scope project --json
+```
+
+Generated pages are written through the artifact store and cataloged in
+`knowledge.db`; index rows and logs are sharded rather than stored in one large
+Markdown file.
+
+## 6. Keep Sources Fresh
+
+Consume open-files outbox events after source changes:
+
+```bash
+open-knowledge reindex outbox ./open-files-outbox.jsonl --scope project --json
+open-knowledge reindex enqueue --scope project --json
+open-knowledge reindex embeddings --scope project --fake --dimensions 8 --json
+```
+
+This invalidates stale source chunks and refreshes embeddings without losing the
+source refs and citation provenance.
+
+## 7. Expose The Wiki To Agents Through MCP
+
+Run MCP over stdio:
+
+```bash
+open-knowledge-mcp
+```
+
+Or run local Streamable HTTP:
+
+```bash
+open-knowledge-mcp --http --port 8819
+```
+
+Agents should prefer stable tools such as `knowledge_search`, `knowledge_ask`,
+`knowledge_build`, `knowledge_get`, `knowledge_lint`, and
+`knowledge_run_status`. They can inspect project resources such as
+`knowledge://project/wiki/pages`, `knowledge://project/runs`, and
+`knowledge://project/open-files`.
+
+## 8. Optional Hosted And S3 Mode
+
+Hosted mode is only a remote client boundary:
+
+```bash
+open-knowledge setup --mode hosted --api-url https://knowledge.hasna.xyz --scope project --json
+open-knowledge remote contracts --scope project --json
+```
+
+Generated artifacts may use S3 when configured, but raw source files still stay
+in `open-files`.

package/docs/migration/json-to-sqlite.md

@@ -0,0 +1,151 @@
+# JSON To SQLite Migration
+
+`open-knowledge` began as a simple JSON note store. Current project mode uses a
+Hasna app workspace and a versioned SQLite catalog:
+
+```text
+.hasna/apps/knowledge/
+  db.json
+  knowledge.db
+  artifacts/
+  indexes/
+  logs/
+  runs/
+  schemas/
+  wiki/
+```
+
+The JSON store remains available for compatibility with note commands such as
+`add`, `list`, `get`, `update`, `delete`, and `export`. The SQLite catalog is
+used for source refs, source revisions, chunks, citations, embeddings, wiki
+pages, generated artifacts, runs, audit events, and reindex jobs.
+
+## What Migrates Automatically
+
+Global legacy notes are migrated on first use:
+
+```text
+~/.open-knowledge/db.json
+```
+
+to:
+
+```text
+~/.hasna/apps/knowledge/db.json
+```
+
+This happens only when the new Hasna JSON store does not already exist. The
+legacy file is not deleted.
+
+Project mode writes directly to:
+
+```text
+<project>/.hasna/apps/knowledge/db.json
+```
+
+when compatibility note commands are used with `--scope project`.
+
+## What Requires Explicit Ingestion
+
+SQLite knowledge records are not inferred from old JSON notes automatically.
+Use explicit commands so provenance, permissions, citations, and redaction are
+recorded correctly.
+
+Initialize the project catalog:
+
+```bash
+open-knowledge db init --scope project --json
+open-knowledge wiki init --scope project --json
+```
+
+Import open-files manifests:
+
+```bash
+open-knowledge ingest manifest ./open-files-manifest.jsonl --scope project --json
+```
+
+Import one allowed source ref:
+
+```bash
+open-knowledge ingest source file:///absolute/path/to/handbook.md \
+  --purpose knowledge_index \
+  --scope project \
+  --json
+```
+
+Resolve indexed source evidence:
+
+```bash
+open-knowledge source resolve open-files://file/file_123/revision/rev_456 \
+  --purpose knowledge_answer \
+  --scope project \
+  --json
+```
+
+## Recommended Migration Path
+
+1. Keep the legacy JSON note store as an exportable compatibility layer.
+2. Run `open-knowledge paths --scope project --json` and confirm the project
+   workspace is `.hasna/apps/knowledge`.
+3. Initialize `knowledge.db` with `open-knowledge db init --scope project`.
+4. Ingest source manifests from `open-files` rather than copying raw files into
+   `open-knowledge`.
+5. Run `open-knowledge search --scope project --json` to verify source chunks.
+6. Run `open-knowledge wiki compile` for durable cited pages.
+7. Run `open-knowledge wiki lint --scope project --json` before treating pages
+   as company knowledge.
+8. Use `open-knowledge export --format jsonl` if legacy notes need to be
+   archived or transformed outside the app.
+
+## JSON Output Contracts
+
+Use `--json` during migration. Commands return stable objects with `ok: true`
+when successful and command-specific fields such as:
+
+- `paths`: workspace paths and config.
+- `db stats`: schema version and table counts.
+- `ingest manifest`: sources, revisions, chunks, redactions, and skipped rows.
+- `source resolve`: read-only source metadata, chunks, citations, and evidence.
+- `search --context`: excerpts, citations, graph evidence, and warnings.
+- `ask|build`: run id, answer, context, citations, proposed wiki updates, write
+  policy, usage, and warnings.
+- `wiki compile`: page id, artifact URI, citations written, index updates, and
+  log shard key.
+
+## Safety Rules During Migration
+
+- Prefer `open-files://` refs for durable company sources.
+- Keep raw source bytes in `open-files`; do not import them as generated wiki
+  artifacts.
+- Enable S3 reads only for allowed buckets:
+
+```bash
+HASNA_KNOWLEDGE_ALLOW_S3_READS=1 \
+HASNA_KNOWLEDGE_ALLOWED_S3_BUCKETS=my-bucket \
+open-knowledge ingest manifest s3://my-bucket/path/manifest.jsonl \
+  --scope project \
+  --json
+```
+
+- Enable web search only when current external context is required:
+
+```bash
+HASNA_KNOWLEDGE_WEB_SEARCH=1 \
+open-knowledge web search "current policy source" --provider openai --json
+```
+
+- Use `--approve-write` only when a generated wiki artifact should be durable.
+
+## Hosted Migration
+
+Hosted mode should not change local migration semantics. It only records a
+remote API boundary:
+
+```bash
+open-knowledge setup --mode hosted --api-url https://knowledge.hasna.xyz --scope project --json
+open-knowledge remote contracts --scope project --json
+```
+
+A SaaS wrapper can later sync generated artifacts, run jobs, enforce tenant ACLs,
+and store artifacts in S3, but the local package remains usable without a hosted
+account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.25",
+  "version": "0.2.27",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -57,6 +57,7 @@ interface Flags {
   provider?: string;
   mode?: string;
   apiUrl?: string;
+  canonicalHasnaXyz?: boolean;
   apiKey?: string;
   email?: string;
   org?: string;
@@ -125,6 +126,7 @@ function parseArgs(argv: string[]): ParseResult {
       case '--provider': flags.provider = argv[i + 1]; i += 1; break;
       case '--mode': flags.mode = argv[i + 1]; i += 1; break;
       case '--api-url': flags.apiUrl = argv[i + 1]; i += 1; break;
+      case '--canonical-hasna-xyz': flags.canonicalHasnaXyz = true; break;
       case '--api-key': flags.apiKey = argv[i + 1]; i += 1; break;
       case '--email': flags.email = argv[i + 1]; i += 1; break;
       case '--org': flags.org = argv[i + 1]; i += 1; break;
@@ -204,7 +206,7 @@ Commands:
   dedupe                       Remove duplicate items by title+content (requires --yes)
   stats                        Show knowledge base statistics
   paths                        Show resolved workspace/store paths
-  setup                        Configure local or hosted mode
+  setup                        Configure local, hosted, or canonical Hasna XYZ S3 mode
   auth login|whoami|logout     Manage hosted API credentials
   remote contracts|status      Inspect hosted client contracts/readiness
   storage status|validate      Inspect local/S3 artifact storage contract
@@ -299,7 +301,7 @@ function printCommandHelp(command: string): void {
   if (command === 'dedupe') { console.log('Usage: open-knowledge dedupe --yes [--json]'); return; }
   if (command === 'stats') { console.log('Usage: open-knowledge stats [--json]'); return; }
   if (command === 'paths') { console.log('Usage: open-knowledge paths [--scope local|global|project] [--json]'); return; }
-  if (command === 'setup') { console.log('Usage: open-knowledge setup --mode local|hosted [--api-url https://...] [--scope local|global|project] [--json]'); return; }
+  if (command === 'setup') { console.log('Usage: open-knowledge setup --mode local|hosted [--api-url https://...] [--canonical-hasna-xyz] [--scope local|global|project] [--json]'); return; }
   if (command === 'auth') { console.log('Usage: open-knowledge auth login|whoami|logout [--api-key <key>] [--email <email>] [--org <slug>] [--api-url https://...] [--scope local|global|project] [--json]'); return; }
   if (command === 'remote') { console.log('Usage: open-knowledge remote contracts|status [--scope local|global|project] [--json]'); return; }
   if (command === 'storage') { console.log('Usage: open-knowledge storage status|validate [--scope local|global|project] [--json]'); return; }
@@ -358,11 +360,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --mode --api-url --api-key --email --org --org-id --user-id --domain --file-results --full --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --mode --api-url --canonical-hasna-xyz --api-key --email --org --org-id --user-id --domain --file-results --full --fake --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--full)--full" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--mode)--mode"\{local,hosted\}:" "(--api-url)--api-url[hosted API URL]:" "(--api-key)--api-key[hosted API key]:" "(--email)--email[email]:" "(--org)--org[org slug]:" "(--org-id)--org-id[org id]:" "(--user-id)--user-id[user id]:" "(--domain)--domain[domain]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--canonical-hasna-xyz)--canonical-hasna-xyz" "(--file-results)--file-results" "(--full)--full" "(--fake)--fake" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--mode)--mode"\{local,hosted\}:" "(--api-url)--api-url[hosted API URL]:" "(--api-key)--api-key[hosted API key]:" "(--email)--email[email]:" "(--org)--org[org slug]:" "(--org-id)--org-id[org id]:" "(--user-id)--user-id[user id]:" "(--domain)--domain[domain]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l mode; complete -c open-knowledge -l api-url; complete -c open-knowledge -l api-key; complete -c open-knowledge -l email; complete -c open-knowledge -l org; complete -c open-knowledge -l org-id; complete -c open-knowledge -l user-id; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l canonical-hasna-xyz; complete -c open-knowledge -l provider; complete -c open-knowledge -l mode; complete -c open-knowledge -l api-url; complete -c open-knowledge -l api-key; complete -c open-knowledge -l email; complete -c open-knowledge -l org; complete -c open-knowledge -l org-id; complete -c open-knowledge -l user-id; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; complete -c open-knowledge -l fake; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l model; complete -c open-knowledge -l dimensions; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -397,6 +399,7 @@ async function run(argv: string[]): Promise<void> {
     const result = service.setup({
       mode: flags.mode,
       apiUrl: flags.apiUrl,
+      canonicalHasnaXyz: flags.canonicalHasnaXyz,
     });
     output(result, flags.json);
     return;

package/src/service.ts

@@ -36,6 +36,7 @@ import {
 } from './storage-contract';
 import { initializeWikiLayout, recordWikiLayoutCatalog } from './wiki-layout';
 import {
+  canonicalHasnaXyzKnowledgeStorage,
   ensureKnowledgeWorkspace,
   readKnowledgeConfig,
   resolveScopedWorkspace,
@@ -70,6 +71,9 @@ export interface KnowledgeSetupResult {
   ok: true;
   mode: KnowledgeConfig['mode'];
   api_url: string | null;
+  storage_type: KnowledgeConfig['storage']['type'];
+  artifact_uri_prefix: string;
+  canonical_hasna_xyz: StorageContract['canonical_hasna_xyz'];
   config_path: string;
   next: string[];
   message: string;
@@ -130,7 +134,7 @@ export class KnowledgeService {
     return validateStorageConfig(this.config(), this.ensureWorkspace());
   }
 
-  setup(options: { mode?: string; apiUrl?: string } = {}): KnowledgeSetupResult {
+  setup(options: { mode?: string; apiUrl?: string; canonicalHasnaXyz?: boolean } = {}): KnowledgeSetupResult {
     const workspace = this.ensureWorkspace();
     const current = this.config();
     const mode = normalizeMode(options.mode) ?? current.mode;
@@ -146,16 +150,23 @@ export class KnowledgeService {
         ...(current.hosted ?? {}),
         ...(apiUrl ? { api_url: apiUrl } : {}),
       },
+      storage: options.canonicalHasnaXyz
+        ? canonicalHasnaXyzKnowledgeStorage()
+        : current.storage,
     };
     writeKnowledgeConfig(workspace.configPath, nextConfig);
     this.cachedConfig = nextConfig;
+    const storage = resolveStorageContract(nextConfig, workspace, this.scope);
     return {
       ok: true,
       mode,
       api_url: nextConfig.hosted?.api_url ?? null,
+      storage_type: nextConfig.storage.type,
+      artifact_uri_prefix: storage.artifact_store.uri_prefix,
+      canonical_hasna_xyz: storage.canonical_hasna_xyz,
       config_path: workspace.configPath,
       next: mode === 'hosted'
-        ? ['open-knowledge auth login --api-key <key>', 'open-knowledge remote contracts --json']
+        ? ['open-knowledge auth login --api-key <key>', 'open-knowledge storage status --json', 'open-knowledge remote contracts --json']
         : ['open-knowledge search <query>', 'knowledge <prompt>'],
       message: `Set knowledge mode to ${mode}`,
     };