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

package/knowledge/ARCHITECTURE.md

@@ -0,0 +1,106 @@
+# Architecture
+
+## Scope
+
+Phase 1 delivers a publishable CLI and Codex skill for a private, local company knowledge workspace.
+
+The implementation is intentionally limited to:
+
+- file-based Markdown roots
+- a derived SQLite index
+- Git-aware verification and history views
+- a read-only local web view
+
+Phase 1 excludes connectors, ingestion pipelines and GUI editing.
+
+## Core Principles
+
+1. Markdown files are the source of truth.
+2. SQLite is a rebuildable, derived index.
+3. Git remains the audit and rollback layer for tracked content.
+4. Agent access goes through the public CLI contract.
+5. The code repository and the private knowledge workspace stay separate.
+
+## Workspace Model
+
+The CLI scaffolds a private workspace with:
+
+- `.company-agent-wiki/workspace.json` as tracked workspace metadata
+- `.company-agent-wiki/index.sqlite` as the derived search index
+- `.company-agent-wiki/index-manifest.json` as the current snapshot manifest
+- `knowledge/canonical/` as the managed Markdown root
+- `knowledge/archive/` as the reserved archive root
+- starter documents such as `wiki-start-here.md`, `company-profile.md`, `organisation-und-rollen.md`, `systeme-und-tools.md`, `kernprozesse.md`, `projekte-und-roadmap.md` and `glossar.md`
+
+The index and manifest are derived artifacts and should stay ignored in the private workspace Git repository.
+
+## Phase 1 Data Flow
+
+1. `setup workspace` creates the private workspace skeleton plus starter documents unless `--no-starter-docs` is used.
+2. `onboarding company` can either emit a source-backed questionnaire or preview/apply draft onboarding documents from an answers file.
+3. `roots add` registers additional local Markdown roots.
+4. `index rebuild` parses Markdown files, sections and frontmatter into SQLite + FTS5.
+5. `verify` compares current root snapshots against the stored manifest and reports `missing` on a brand-new workspace instead of failing hard.
+6. `search` and `route` can narrow candidates with front-matter filters such as `type`, `project`, `department`, `tag`, `owner` and `system`.
+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.
+
+## Onboarding Model
+
+Phase 1 includes a source-backed onboarding blueprint for das deutsche Unternehmensprofil. The agent can now turn an answer file into draft starter Markdown under `knowledge/canonical/`, but the write step is still explicit and guarded by `--execute`.
+
+The onboarding scope standardizes the first agent-led questions around:
+
+- rechtliche Identität
+- Geschäftsführung und Eigentum
+- Steuern und Umsatzsteuerlogik
+- Mitarbeitende und Arbeitgeberstatus
+- operative Wissensgrundlage
+
+## Snapshot and Staleness Contract
+
+The manifest stores:
+
+- `build_id`
+- `schema_version`
+- `indexed_at`
+- per-root fingerprints based on file paths, sizes and mtimes
+- optional Git snapshot metadata for Git-backed roots
+
+Reads are pinned to the latest successful `build_id`. If current root snapshots no longer match the manifest, the CLI returns `INDEX_STALE` unless the caller explicitly opted into auto-rebuild.
+
+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.
+
+## Metadata-First Retrieval
+
+Phase 1 now explicitly supports a two-step retrieval model:
+
+1. candidate routing through search plus indexed metadata
+2. metadata and heading inspection before full document reads
+
+This keeps the agent loop lighter and encourages stronger filenames plus front matter without forcing a rigid folder taxonomy.
+
+## Git Model
+
+Phase 1 uses Git for:
+
+- workspace repository initialization
+- document history lookup
+- document diff lookup
+- optional remote registration during setup
+- reviewing explicit onboarding-generated draft Markdown after it has been written
+
+Phase 1 deliberately does not auto-commit content mutations. Even onboarding writes stay outside automatic Git mutation flows, though the CLI now rebuilds the derived index after a successful onboarding apply.
+
+## Why the Workspace Is Separate
+
+This repository is meant to be public. A real company knowledge workspace is private by design and may contain:
+
+- confidential process documentation
+- customer-specific notes
+- accounting procedures
+- sensitive internal structures
+
+Separating code and private data keeps the public package clean and keeps Git, npm and screenshots safe by default.

package/knowledge/KNOWN_LIMITATIONS.md

@@ -0,0 +1,30 @@
+# Known Limitations
+
+## Product Scope
+
+- Phase 1 only understands local Markdown roots.
+- Connectors for e-mail, notes, CRM, chat or audio are not implemented.
+- The web view is read-only.
+- The CLI only materializes onboarding-generated draft starter documents from an explicit answers file.
+- The onboarding flow is not a built-in interactive prompt loop; the agent still has to conduct the conversation and produce the answers file.
+
+## Index Model
+
+- Root freshness is based on file path, size and mtime snapshots, not on deep content hashing for every query.
+- The SQLite index is rebuilt wholesale through `index rebuild`; there is no incremental mutation journal yet.
+- 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.
+- 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
+
+- History and diff only work for files inside a Git repository.
+- Phase 1 does not auto-commit workspace changes.
+- Restore flows are not implemented in the web view.
+
+## Security Model
+
+- 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.

package/knowledge/RELEASE_CHECKLIST.md

@@ -0,0 +1,145 @@
+# Release Checklist
+
+## Naming Decision
+
+- Empfohlener GitHub-Repo-Name: `company-agent-wiki-skill`
+- npm-Paket: `@codecell-germany/company-agent-wiki-skill`
+- CLI-Binary: `company-agent-wiki-cli`
+- Installer-Binary: `company-agent-wiki-skill`
+- Skill-Name: `company-agent-wiki-cli`
+
+Empfohlene GitHub-Beschreibung:
+
+`Context is king. Agent-first local company knowledge runtime with Markdown as truth, metadata-first retrieval, a SQLite index and Git-aware history.`
+
+## Before GitHub Publish
+
+- Prüfen, dass das lokale Git-Repo einen sauberen Ausgangszustand hat:
+  - wenn noch kein erster Commit existiert, zuerst den initialen Commit vorbereiten
+  - wenn noch kein Remote existiert, das öffentliche GitHub-Repo zuerst anlegen
+- Prüfen, dass keine privaten Daten im Repo liegen:
+  - keine echten Workspace-Inhalte
+  - keine Tokens, `.env`-Dateien oder Exportdateien
+  - keine Inhalte aus `Plans/`, `.context/` oder `output/`
+- Prüfen, dass `.gitignore` mindestens diese Bereiche abdeckt:
+  - `Plans/`
+  - `.context/`
+  - `output/`
+  - `.env`
+  - `.env.*`
+  - `*.tgz`
+- Prüfen, dass `package.json -> files` nur öffentliche Artefakte freigibt.
+- README, Skill, Referenzen und Knowledge-Doku gemeinsam synchronisieren:
+  - `README.md`
+  - `skills/company-agent-wiki-cli/SKILL.md`
+  - `skills/company-agent-wiki-cli/references/agent-onboarding.md`
+  - `skills/company-agent-wiki-cli/references/overview.md`
+  - `skills/company-agent-wiki-cli/references/command-cheatsheet.md`
+  - `skills/company-agent-wiki-cli/references/workspace-first-run.md`
+  - `skills/company-agent-wiki-cli/references/authoring-workflow.md`
+  - `knowledge/ARCHITECTURE.md`
+  - `knowledge/KNOWN_LIMITATIONS.md`
+
+## Local Verification
+
+```bash
+npm install
+npm run build
+npm run test:unit
+node dist/index.js --help
+node dist/installer.js install --force
+npm pack
+```
+
+## Tarball Smoke Tests
+
+CLI aus lokalem Tarball:
+
+```bash
+TMP="$(mktemp -d)"
+cd "$TMP"
+npx -y -p /absolute/path/to/codecell-germany-company-agent-wiki-skill-0.1.0.tgz company-agent-wiki-cli --help
+```
+
+Installer aus lokalem Tarball:
+
+```bash
+TMP="$(mktemp -d)"
+cd "$TMP"
+npx -y -p /absolute/path/to/codecell-germany-company-agent-wiki-skill-0.1.0.tgz company-agent-wiki-skill install --codex-home "$TMP/codex" --force
+"$TMP/codex/bin/company-agent-wiki-cli" --help
+```
+
+## GitHub Publish Order
+
+1. Öffentliches GitHub-Repo `codecell-germany/company-agent-wiki-skill` anlegen.
+2. GitHub-Beschreibung setzen.
+3. Lokale Dateien prüfen und nur gewünschte Dateien stagen.
+4. Ersten Commit oder Release-Commit erstellen.
+5. Remote verbinden.
+6. Push ausführen.
+
+Wichtige Regel:
+
+- niemals blind `git add .`
+
+## npm Publish
+
+Vor dem Publish:
+
+```bash
+npm whoami
+npm pack
+```
+
+Veröffentlichung:
+
+```bash
+npm publish --access public --registry=https://registry.npmjs.org/
+```
+
+Wenn npm-2FA blockiert, den finalen Publish-Schritt lokal im echten Terminal ausführen.
+
+## npm Verification After Publish
+
+```bash
+npm view @codecell-germany/company-agent-wiki-skill version --registry=https://registry.npmjs.org/
+npm view @codecell-germany/company-agent-wiki-skill dist-tags --json --registry=https://registry.npmjs.org/
+```
+
+Registry-Install mit exakter Version:
+
+```bash
+TMP="$(mktemp -d)"
+CACHE="$(mktemp -d)"
+cd "$TMP"
+npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.0 company-agent-wiki-cli --help
+npm_config_cache="$CACHE" npx -y @codecell-germany/company-agent-wiki-skill@0.1.0 company-agent-wiki-skill install --codex-home "$TMP/codex" --force
+"$TMP/codex/bin/company-agent-wiki-cli" --help
+```
+
+## skills.sh Verification
+
+Nach GitHub-Publish:
+
+```bash
+npx -y skills add codecell-germany/company-agent-wiki-skill -l
+```
+
+Danach einen echten Install testen:
+
+```bash
+npx -y skills add codecell-germany/company-agent-wiki-skill -g --skill company-agent-wiki-cli -a '*' -y
+```
+
+## Final Done Check
+
+- CLI läuft über `company-agent-wiki-cli`
+- Installer läuft über `company-agent-wiki-skill`
+- README, Skill, Referenzen und Knowledge sind synchron
+- `npm pack` enthält nur gewollte Dateien
+- lokaler Tarball-Smoketest ist grün
+- GitHub-Repo ist öffentlich und aktuell
+- npm-Paket ist veröffentlicht
+- exakter Registry-Install ist verifiziert
+- `skills add ... -l` findet den Skill

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@codecell-germany/company-agent-wiki-skill",
+  "version": "0.1.0",
+  "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",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "bin": {
+    "company-agent-wiki-cli": "dist/index.js",
+    "company-agent-wiki-skill": "dist/installer.js"
+  },
+  "files": [
+    "dist/**",
+    "skills/**",
+    "knowledge/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.10"
+  },
+  "scripts": {
+    "clean": "rm -rf dist coverage",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run clean && npm run typecheck && node scripts/build.mjs",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.15.3",
+    "commander": "^14.0.0",
+    "esbuild": "^0.25.3",
+    "gray-matter": "^4.0.3",
+    "marked": "^15.0.12",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}

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

@@ -0,0 +1,252 @@
+---
+name: company-agent-wiki-cli
+description: Use when an agent must set up, onboard, verify, index, search or browse a private local company knowledge workspace that uses Markdown as truth, SQLite as derived index and Git for history. Covers first-run setup, company-profile questioning, root registration, stale-index checks, read-only web browsing, document history and diff workflows.
+---
+
+# Company Agent Wiki CLI
+
+Use this skill when the task is about a private company knowledge workspace built around:
+
+- local Markdown roots
+- a rebuildable SQLite index
+- Git-backed history
+- a read-only local browsing view
+
+## Preconditions
+
+- 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.
+- 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.
+- `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
+node dist/index.js --help
+```
+
+## First Run
+
+1. In Codex, start with the explicit shim paths:
+
+```bash
+"$CODEX_HOME/bin/company-agent-wiki-cli" --help
+"$HOME/.codex/bin/company-agent-wiki-cli" --help
+```
+
+If that fails, try the PATH binary as a convenience fallback:
+
+```bash
+company-agent-wiki-cli --help
+```
+
+Only if the package is already published should you rely on:
+
+```bash
+npx -p @codecell-germany/company-agent-wiki-skill company-agent-wiki-cli --help
+```
+
+2. If no private workspace exists yet, create one:
+
+```bash
+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.
+
+3. Run health checks:
+
+```bash
+company-agent-wiki-cli doctor --workspace /absolute/path/to/private-company-knowledge --json
+```
+
+4. Build the index:
+
+```bash
+company-agent-wiki-cli index rebuild --workspace /absolute/path/to/private-company-knowledge --json
+```
+
+5. Only then use `search`, `route`, `read`, `history`, `diff` or `serve`.
+
+If a human expects a browser view, you must explicitly start it with:
+
+```bash
+company-agent-wiki-cli serve --workspace /absolute/path/to/private-company-knowledge --port 4187
+```
+
+The web view is provided by the installed CLI. The private workspace itself is not a frontend repo.
+
+If the authoring loop is noisy, prefer the auto-rebuild variants:
+
+```bash
+company-agent-wiki-cli search "KI-Telefonassistent" --workspace /absolute/path --auto-rebuild --json
+company-agent-wiki-cli route "Eingangsrechnung AWS" --workspace /absolute/path --auto-rebuild --json
+company-agent-wiki-cli read --doc-id canonical.company-profile --workspace /absolute/path --metadata --headings --auto-rebuild --json
+company-agent-wiki-cli read --doc-id canonical.company-profile --workspace /absolute/path --auto-rebuild
+company-agent-wiki-cli serve --workspace /absolute/path --port 4187 --auto-rebuild
+```
+
+## Retrieval-Prozess Für Agenten
+
+Der empfohlene Lesepfad ist jetzt explizit metadata-first:
+
+1. Zuerst mit `search` oder `route` Kandidaten finden.
+2. Wenn möglich direkt mit Front-Matter-Filtern eingrenzen, zum Beispiel `--type`, `--project`, `--department`, `--tag`, `--owner` oder `--system`.
+3. Danach Kandidaten mit `read --metadata --headings --auto-rebuild` prüfen.
+4. Erst wenn Metadaten, Dateiname und Überschriften passen, den Volltext mit `read --auto-rebuild` laden.
+
+Beispiel:
+
+```bash
+company-agent-wiki-cli route "Projekt Alpha Budget" --workspace /absolute/path --type project --project alpha --auto-rebuild --json
+company-agent-wiki-cli read --workspace /absolute/path --doc-id canonical.projekt-alpha-roadmap --metadata --headings --auto-rebuild --json
+company-agent-wiki-cli read --workspace /absolute/path --doc-id canonical.projekt-alpha-roadmap --auto-rebuild
+```
+
+## Anlageprozess Für Neues Wissen
+
+Wenn ein Agent neues Wissen anlegt, soll er nicht mit beliebigen Dateinamen oder leerem Front Matter arbeiten.
+
+Pflichtgedanke:
+
+1. sprechender Dateiname
+2. klares Front Matter
+3. gute Abschnittsstruktur
+4. danach Index aktualisieren
+
+Empfohlenes Minimal-Front-Matter:
+
+```yaml
+---
+id: projects.alpha.roadmap
+title: Projekt Alpha Roadmap
+type: project
+status: draft
+tags:
+  - projekt
+  - alpha
+summary: Roadmap und Entscheidungen für Projekt Alpha.
+project: alpha
+department: entwicklung
+owners:
+  - nikolas-gottschol
+systems:
+  - linear
+---
+```
+
+`id` ist jetzt klar empfohlen. Es ist technisch noch nicht in jedem Dokument Pflicht, aber für neues Wissen solltest du eine stabile manuelle ID setzen, damit spätere Referenzen, History und Routing nicht am Dateinamen hängen.
+
+Empfohlener Ablauf:
+
+1. Datei unter `knowledge/canonical/` oder einem anderen registrierten Managed Root anlegen.
+2. Dateiname so wählen, dass er den Inhalt grob repräsentiert, etwa `projekt-alpha-roadmap.md`.
+3. Front Matter inklusive `id`, `summary` und passenden Routing-Feldern setzen.
+4. Wenn der Inhalt auf externer Recherche basiert, Provenienz ergänzen:
+   - Quellenstand oder Prüfdokumentation im Dokument
+   - Datum der Prüfung
+   - Quelle oder URL
+   - kurze Einordnung, ob Primärquelle, Sekundärquelle oder Nutzerangabe
+5. Inhalt in sinnvolle `#`, `##`, `###`-Abschnitte gliedern.
+6. `company-agent-wiki-cli index rebuild --workspace /absolute/path --json` ausführen oder einen `--auto-rebuild`-Pfad nutzen.
+7. Mit `read --metadata --headings --auto-rebuild` prüfen, ob das Dokument für spätere Agenten sauber routbar ist.
+8. Navigation und Einstiegspunkte aktualisieren, wenn das Dokument strukturell wichtig ist:
+   - Startseite
+   - thematische README
+   - Prozess- oder Projektübersicht
+
+## Bestehendes Wissen Erweitern
+
+Nicht jeder Wissenszuwachs braucht ein neues Dokument.
+
+Wenn bereits eine passende Seite existiert:
+
+1. erst mit `route` oder `search` plus Filtern prüfen, ob das Wissen schon einen guten Zielort hat
+2. mit `read --metadata --headings --auto-rebuild` die bestehende Struktur ansehen
+3. nur dann erweitern, wenn Thema, Typ und Zielgruppe wirklich passen
+4. sonst ein neues Dokument anlegen und die bestehende Navigation verlinken
+
+Faustregel:
+
+- neuer Prozess oder neues Themencluster: neues Dokument
+- zusätzliche Ausnahme, Ergänzung oder Quellenstand zu bestehendem Thema: bestehendes Dokument erweitern
+
+## Muster Für Beziehungswissen
+
+Für Partner-, Netzwerk- oder CRM-Wissen ist dieses Muster sinnvoll:
+
+```yaml
+---
+id: crm.partner.beispiel-partner
+title: Beispiel Partner
+type: relationship
+status: draft
+tags:
+  - crm
+  - partner
+  - netzwerk
+summary: Rolle, Status und Relevanz des Partners im CodeCell-Netzwerk.
+department: vertrieb
+owners:
+  - nikolas-gottschol
+---
+```
+
+Im Dokument selbst:
+
+- Rolle: Partner, Netzwerkpartner, potenzieller Kunde, bestätigter Kunde
+- Beziehung: Seit wann, über wen, in welchem Kontext
+- Relevanz: strategisch, operativ, vertrieblich, technisch
+- Aktueller Stand: offen, aktiv, pausiert, abgeschlossen
+- Nächste Schritte
+- Quellenstand
+
+If the company profile itself is still unclear, run the onboarding questionnaire before deep indexing work:
+
+```bash
+company-agent-wiki-cli onboarding company
+```
+
+If the agent already has structured answers, preview or apply the generated draft onboarding documents:
+
+```bash
+company-agent-wiki-cli onboarding company \
+  --workspace /absolute/path/to/private-company-knowledge \
+  --answers-file /absolute/path/to/company-onboarding-answers.json
+company-agent-wiki-cli onboarding company \
+  --workspace /absolute/path/to/private-company-knowledge \
+  --answers-file /absolute/path/to/company-onboarding-answers.json \
+  --execute
+```
+
+`--execute` requires `--answers-file`, and `--force` only works together with `--execute`.
+
+## Operating Rules
+
+- Treat Markdown files as the source of truth.
+- Treat SQLite as derived and rebuildable.
+- 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.
+- 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.
+
+## References
+
+- Overview: [references/overview.md](references/overview.md)
+- Agent onboarding: [references/agent-onboarding.md](references/agent-onboarding.md)
+- Authoring workflow: [references/authoring-workflow.md](references/authoring-workflow.md)
+- Command cheatsheet: [references/command-cheatsheet.md](references/command-cheatsheet.md)
+- Workspace setup details: [references/workspace-first-run.md](references/workspace-first-run.md)
+- Company onboarding questions: [references/company-onboarding.md](references/company-onboarding.md)

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

@@ -0,0 +1,57 @@
+# Agent Onboarding
+
+## Use This Sequence
+
+```bash
+"$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 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
+company-agent-wiki-cli doctor --workspace /absolute/path --json
+company-agent-wiki-cli index rebuild --workspace /absolute/path --json
+company-agent-wiki-cli verify --workspace /absolute/path --json
+company-agent-wiki-cli serve --workspace /absolute/path --port 4187 --auto-rebuild
+```
+
+Only after the company profile is clear enough and these checks succeed should you search or browse deeply.
+
+## If the Workspace Does Not Exist Yet
+
+```bash
+company-agent-wiki-cli setup workspace --workspace /absolute/path --git-init
+```
+
+If the human has a private Git remote ready:
+
+```bash
+company-agent-wiki-cli setup workspace \
+  --workspace /absolute/path \
+  --git-init \
+  --git-remote git@github.com:your-org/private-company-knowledge.git
+```
+
+## If `INDEX_STALE` Appears
+
+Run:
+
+```bash
+company-agent-wiki-cli index rebuild --workspace /absolute/path --json
+```
+
+Do not continue with stale results.
+
+For frequent edits, the authoring loop can also use the guarded auto-rebuild path:
+
+```bash
+company-agent-wiki-cli search "KI-Telefonassistent" --workspace /absolute/path --auto-rebuild --json
+```
+
+After candidate routing, prefer metadata-first reading:
+
+```bash
+company-agent-wiki-cli read --workspace /absolute/path --doc-id canonical.projekt-alpha-roadmap --metadata --headings --auto-rebuild --json
+company-agent-wiki-cli read --workspace /absolute/path --doc-id canonical.projekt-alpha-roadmap --auto-rebuild
+```