@codecell-germany/company-agent-wiki-skill 0.1.0 → 0.1.2

package/dist/installer.js

@@ -3473,7 +3473,7 @@ var {
 var CLI_NAME = "company-agent-wiki-cli";
 var INSTALLER_NAME = "company-agent-wiki-skill";
 var SKILL_NAME = "company-agent-wiki-cli";
-var CLI_SCHEMA_VERSION = "2026-04-12";
+var CLI_SCHEMA_VERSION = "2026-04-13";
 var EXIT_CODES = {
   ok: 0,
   usage: 1,
@@ -3484,6 +3484,7 @@ var EXIT_CODES = {
   notFound: 6,
   git: 7,
   sqliteLocked: 8,
+  workspaceBusy: 9,
   runtime: 10
 };
 

package/knowledge/ARCHITECTURE.md

@@ -45,7 +45,8 @@ The index and manifest are derived artifacts and should stay ignored in the priv
 7. `read --metadata --headings` supports a metadata-first retrieval pass before the full Markdown is loaded.
 8. `search`, `route` and `read` either enforce a fresh index or can explicitly auto-rebuild when `--auto-rebuild` is set.
 9. Runtime commands may detect the current workspace automatically when the shell is already inside a private workspace.
-10. `serve` exposes the same read-only data through a local web view and now distinguishes `missing`, `stale` and `ok` states with a rebuild action.
+10. A global per-user workspace registry stores known workspace paths and a default workspace so other agents can resolve the knowledge location automatically on macOS, Windows and Linux.
+11. `serve` exposes the same read-only data through a local web view and now distinguishes `missing`, `stale` and `ok` states with a rebuild action.
 
 ## Onboarding Model
 
@@ -73,6 +74,8 @@ Reads are pinned to the latest successful `build_id`. If current root snapshots
 
 The SQLite runtime also uses a busy timeout and returns a specific `SQLITE_LOCKED` error for transient contention instead of surfacing a generic runtime failure.
 
+Phase 1 now also adds a workspace-local write lock. The lock serializes rebuilds and other write flows per workspace, while parallel readers continue against the current derived index.
+
 ## Metadata-First Retrieval
 
 Phase 1 now explicitly supports a two-step retrieval model:
@@ -82,6 +85,21 @@ Phase 1 now explicitly supports a two-step retrieval model:
 
 This keeps the agent loop lighter and encourages stronger filenames plus front matter without forcing a rigid folder taxonomy.
 
+## Global Workspace Discovery
+
+Phase 1 now persists workspace discovery outside the private workspace itself:
+
+- macOS: `~/Library/Application Support/company-agent-wiki/workspaces.json`
+- Windows: `%APPDATA%\\company-agent-wiki\\workspaces.json`
+- Linux: `${XDG_CONFIG_HOME:-~/.config}/company-agent-wiki/workspaces.json`
+
+The registry stores known workspace paths plus a default workspace. `setup workspace` registers the workspace automatically. Runtime commands prefer:
+
+1. explicit `--workspace`
+2. current-directory detection
+3. global default workspace
+4. the single registered workspace, if exactly one exists
+
 ## Git Model
 
 Phase 1 uses Git for:

package/knowledge/KNOWN_LIMITATIONS.md

@@ -15,7 +15,8 @@
 - Auto-rebuild is opt-in. Without `--auto-rebuild`, stale or missing indexes still block retrieval on purpose.
 - Search quality depends on document structure and heading hygiene in the source Markdown.
 - Front-matter filters are currently focused on common fields such as `type`, `status`, `tags`, `project`, `department`, `owners` and `systems`; there is not yet a generic arbitrary-field query language.
-- The SQLite runtime is more tolerant of transient contention now, but the same workspace should still not be hammered by multiple parallel agent reads if that can be avoided.
+- Parallel reads are supported, but there is still only one active write path per workspace at a time.
+- Long-running rebuilds can delay later auto-rebuild requests because they queue behind the same workspace lock.
 - Search JSON now exposes a normalized `score` plus `rawScore`; the normalized value is better for agents, but it is still only a ranking aid, not a calibrated relevance percentage.
 
 ## Git Model
@@ -28,3 +29,4 @@
 
 - The CLI can initialize a private Git remote URL, but it does not validate remote policy or access controls.
 - The package does not enforce OS-level filesystem permissions; the workspace owner must place the private workspace in a properly protected location.
+- The global workspace registry is only a discovery layer, not an access-control boundary. Any agent running as the same local user can read the registered workspace path.

package/knowledge/RELEASE_CHECKLIST.md

@@ -118,6 +118,25 @@ npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.
 "$TMP/codex/bin/company-agent-wiki-cli" --help
 ```
 
+Falls `npm view` direkt nach dem Publish kurzfristig noch `404` liefert, zusätzlich die Registry-Tarball-URL prüfen und daraus den Install-Smoke fahren:
+
+```bash
+curl -I https://registry.npmjs.org/@codecell-germany/company-agent-wiki-skill/-/company-agent-wiki-skill-0.1.0.tgz
+TMP="$(mktemp -d)"
+cd "$TMP"
+npx -y -p https://registry.npmjs.org/@codecell-germany/company-agent-wiki-skill/-/company-agent-wiki-skill-0.1.0.tgz company-agent-wiki-cli --help
+```
+
+Praktisches Learning aus diesem Release:
+
+- `npm dist-tag ls` und die direkte Tarball-URL können bereits korrekt funktionieren, während `npm view` bzw. die Packument-Auflösung noch kurz hinterherhinkt.
+- Für die Veröffentlichungsfreigabe reicht deshalb im Zweifel:
+  - erfolgreicher `npm publish`
+  - `npm access get status <package>` = `public`
+  - `npm dist-tag ls <package>` zeigt `latest`
+  - Tarball-URL liefert `200`
+  - CLI-/Installer-Smoke direkt von der Tarball-URL funktioniert
+
 ## skills.sh Verification
 
 Nach GitHub-Publish:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codecell-germany/company-agent-wiki-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Context is king: agent-first local company knowledge workspace with metadata-first retrieval, Markdown as truth, SQLite-indexed front matter, Git-aware verification, and a Codex skill installer.",
   "private": false,
   "license": "MIT",

package/skills/company-agent-wiki-cli/SKILL.md

@@ -17,17 +17,18 @@ Use this skill when the task is about a private company knowledge workspace buil
 - The public CLI binary is `company-agent-wiki-cli`.
 - The actual company knowledge workspace is private and lives outside the public code repository.
 - The private workspace may be the current dedicated local folder; it just must not be the public skill/CLI repo.
-- The human should provide the workspace path and, if desired, the private Git remote URL. If the current folder is already inside a private workspace, the CLI may detect it automatically.
+- The human should provide the workspace path at least once and, if desired, the private Git remote URL. After setup or manual registration, the CLI stores the workspace path in a global per-user registry so later agents can resolve it automatically.
 - Runtime discovery matters. Before relying on the CLI, verify which path is actually available.
 - In Codex, the most reliable fallback is usually the installed shim under `$CODEX_HOME/bin` or `~/.codex/bin`.
-- The `npx -p @codecell-germany/company-agent-wiki-skill ...` path only works after the npm package is really published.
+- The preferred one-command installer path is `npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force`. This only works after the npm package is really published.
 - `node dist/index.js` only works inside the public implementation repo after `npm run build`, not inside an arbitrary private workspace.
 - If the binary is not already installed in PATH, use these fallbacks in this order:
 
 ```bash
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
-npx -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-cli --help
+company-agent-wiki-cli --help
+npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
 node dist/index.js --help
 ```
 
@@ -46,10 +47,10 @@ If that fails, try the PATH binary as a convenience fallback:
 company-agent-wiki-cli --help
 ```
 
-Only if the package is already published should you rely on:
+If the CLI is not installed yet and the package is already published, install it with one command:
 
 ```bash
-npx -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-cli --help
+npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
 ```
 
 2. If no private workspace exists yet, create one:
@@ -58,7 +59,15 @@ npx -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-cli --help
 company-agent-wiki-cli setup workspace --workspace /absolute/path/to/private-company-knowledge --git-init
 ```
 
-This creates starter Markdown documents by default. Use `--no-starter-docs` only when you explicitly want a nearly empty workspace.
+This creates starter Markdown documents by default and registers the workspace globally for future agents. Use `--no-starter-docs` only when you explicitly want a nearly empty workspace.
+
+If the workspace already exists, inspect or register it explicitly:
+
+```bash
+company-agent-wiki-cli workspace current --json
+company-agent-wiki-cli workspace list --json
+company-agent-wiki-cli workspace register --workspace /absolute/path/to/private-company-knowledge --default --json
+```
 
 3. Run health checks:
 
@@ -234,13 +243,19 @@ company-agent-wiki-cli onboarding company \
 - The local SQLite file lives in the workspace, but should stay out of Git by default.
 - If the CLI reports `INDEX_STALE`, do not ignore it. Run `index rebuild` or use an explicit `--auto-rebuild` path.
 - For agent workflows, prefer `--auto-rebuild` on `search`, `route`, `read` and `serve` unless you explicitly want strict stale-index failures.
-- Avoid parallel `search`, `route`, `read`, `history` and `diff` calls against the same workspace when possible. SQLite contention is now surfaced clearly, but agent-side serialization is still the safer Phase-1 pattern.
+- Parallel `search`, `route`, `read`, `history` and `diff` calls against the same workspace are now intended to work.
+- Write paths are serialized per workspace. If one agent is rebuilding the index or applying onboarding writes, other write paths wait behind that workspace lock instead of colliding.
 - Do not put private company knowledge into the public code repository.
 - Use the read-only web view only for browsing, not editing.
 - The company onboarding questionnaire is optional. Every answer may be skipped, answered with “nein” or marked as unknown.
 - Onboarding writes are explicit. Do not assume preview mode changes files; only `--execute` writes draft onboarding Markdown and rebuilds the derived index.
 - If CLI discovery fails, do not pretend the documented command works. First resolve a real executable path.
 - If the current folder already contains `.company-agent-wiki/workspace.json`, you may omit `--workspace` and let the CLI detect the workspace root automatically.
+- If the current folder is not inside the workspace, the CLI may still resolve the globally registered default workspace.
+- The global workspace registry lives per user:
+  - macOS: `~/Library/Application Support/company-agent-wiki/workspaces.json`
+  - Windows: `%APPDATA%\\company-agent-wiki\\workspaces.json`
+  - Linux: `${XDG_CONFIG_HOME:-~/.config}/company-agent-wiki/workspaces.json`
 
 ## References
 

package/skills/company-agent-wiki-cli/references/agent-onboarding.md

@@ -3,10 +3,13 @@
 ## Use This Sequence
 
 ```bash
+npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli --help
 company-agent-wiki-cli setup workspace --workspace /absolute/path --git-init
+company-agent-wiki-cli workspace current --json
+company-agent-wiki-cli workspace list --json
 company-agent-wiki-cli onboarding company
 company-agent-wiki-cli onboarding company --workspace /absolute/path --answers-file /absolute/path/to/answers.json
 company-agent-wiki-cli onboarding company --workspace /absolute/path --answers-file /absolute/path/to/answers.json --execute
@@ -24,6 +27,8 @@ Only after the company profile is clear enough and these checks succeed should y
 company-agent-wiki-cli setup workspace --workspace /absolute/path --git-init
 ```
 
+This setup step also registers the workspace globally so later agents can find it without asking for the same path again.
+
 If the human has a private Git remote ready:
 
 ```bash
@@ -49,6 +54,8 @@ For frequent edits, the authoring loop can also use the guarded auto-rebuild pat
 company-agent-wiki-cli search "KI-Telefonassistent" --workspace /absolute/path --auto-rebuild --json
 ```
 
+Parallel reads are allowed. If a write path such as `index rebuild` is already running, later writes wait behind the same workspace lock.
+
 After candidate routing, prefer metadata-first reading:
 
 ```bash

package/skills/company-agent-wiki-cli/references/command-cheatsheet.md

@@ -3,10 +3,15 @@
 ## Workspace
 
 ```bash
+npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli about --json
 company-agent-wiki-cli setup workspace --workspace /absolute/path --git-init
+company-agent-wiki-cli workspace current --json
+company-agent-wiki-cli workspace list --json
+company-agent-wiki-cli workspace register --workspace /absolute/path --default --json
+company-agent-wiki-cli workspace use --workspace /absolute/path --json
 company-agent-wiki-cli onboarding company
 company-agent-wiki-cli onboarding company --workspace /absolute/path --answers-file /absolute/path/to/answers.json
 company-agent-wiki-cli onboarding company --workspace /absolute/path --answers-file /absolute/path/to/answers.json --execute
@@ -23,6 +28,7 @@ company-agent-wiki-cli verify --workspace /absolute/path --json
 ```
 
 If you are already inside the private workspace, `doctor`, `verify`, `search`, `route`, `read`, `history`, `diff` and `serve` may omit `--workspace`.
+If not, the CLI can also use the globally registered default workspace.
 
 ## Retrieval
 

package/skills/company-agent-wiki-cli/references/overview.md

@@ -16,6 +16,7 @@
 ## Main Commands
 
 - `setup workspace`
+- `workspace current|list|register|use`
 - `onboarding company`
 - `doctor`
 - `verify`
@@ -32,10 +33,13 @@
 ## Expected Workflow
 
 1. Set up the private workspace.
-2. Use the starter documents or run `onboarding company`, then preview or apply the generated onboarding Markdown from an answers file.
-3. Register any additional Markdown roots.
-4. Rebuild the index.
-5. Verify that the snapshot is fresh. On a brand-new workspace `verify` reports `missing` instead of failing hard.
-6. Search or route to the right document. For active authoring loops, prefer `--auto-rebuild` and front-matter filters such as `--type`, `--project` or `--department`.
-7. Inspect metadata and headings with `read --metadata --headings --auto-rebuild`.
-8. Read the full source document or use the read-only web view.
+2. The workspace is registered globally so other agents can discover it automatically.
+3. Use the starter documents or run `onboarding company`, then preview or apply the generated onboarding Markdown from an answers file.
+4. Register any additional Markdown roots.
+5. Rebuild the index.
+6. Verify that the snapshot is fresh. On a brand-new workspace `verify` reports `missing` instead of failing hard.
+7. Search or route to the right document. For active authoring loops, prefer `--auto-rebuild` and front-matter filters such as `--type`, `--project` or `--department`.
+8. Inspect metadata and headings with `read --metadata --headings --auto-rebuild`.
+9. Read the full source document or use the read-only web view.
+
+Parallel reads are supported. Writes are serialized per workspace.

package/skills/company-agent-wiki-cli/references/workspace-first-run.md

@@ -5,6 +5,8 @@
 - a private workspace folder path
 - if desired, a private Git remote URL
 
+The workspace path only has to be provided once. After setup or manual registration, the CLI stores it in a per-user global registry for later agents.
+
 ## What the Agent Can Safely Do
 
 - scaffold the local workspace
@@ -13,6 +15,7 @@
 - create the default starter documents for the first useful company knowledge
 - preview or apply onboarding-generated starter Markdown from an answers file
 - register Markdown roots
+- register the workspace globally for later agents
 - rebuild the derived index
 - verify freshness or a still-missing first index
 - run the read-only web view via `company-agent-wiki-cli serve --workspace /absolute/path --port 4187`
@@ -22,14 +25,22 @@
 Before relying on the CLI, verify a real executable path:
 
 ```bash
+npx -y -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-skill install --force
 "$CODEX_HOME/bin/company-agent-wiki-cli" --help
 "$HOME/.codex/bin/company-agent-wiki-cli" --help
 company-agent-wiki-cli --help
 ```
 
-The package-based `npx` path is only valid once the npm package is published.
+The package-based `npx` installer path is only valid once the npm package is published.
 
 If the current folder is already inside a private workspace, runtime commands may omit `--workspace`.
+If not, inspect or update the global registry:
+
+```bash
+company-agent-wiki-cli workspace current --json
+company-agent-wiki-cli workspace list --json
+company-agent-wiki-cli workspace register --workspace /absolute/path --default --json
+```
 
 ## What Must Stay Out of This Public Repo