Replace implicit note shorthand with explicit addnote command and split README

Two changes: 1. structured-add-commands: The implicit note shorthand (kb "text") caused accidental note creation from mistyped commands. Replaced with explicit kb addnote <text> command. Root command reverts to standard Cobra behaviour. Updated examples, tests, SKILL.md, and specs. 2. split-readme-developer-docs: Moved build-from-source instructions, release process, API reference, and ROCm migration notes from README.md into a new DEVELOPER.md. README now links to DEVELOPER.md for dev workflows. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-31 20:48:22 +01:00
parent 9e957f1a9a
commit afbe270181
20 changed files with 688 additions and 242 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-31
@@ -0,0 +1,52 @@
+## Context
+
+README.md currently serves as a single documentation file for both users and developers. It contains ~290 lines mixing installation/usage instructions with build-from-source steps, release scripts, Docker image internals, and developer notes (e.g., ROCm migration plans). There is no DEVELOPER.md or CONTRIBUTING.md file.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Separate user-facing documentation (README.md) from developer-facing documentation (DEVELOPER.md)
+- README.md should answer: "What is this? How do I install it? How do I use it?"
+- DEVELOPER.md should answer: "How do I build from source? How do I release? How do I contribute?"
+- Provide a clear cross-reference link between the two files
+
+**Non-Goals:**
+- Rewriting or improving documentation content itself (just moving it)
+- Creating additional docs files (CONTRIBUTING.md, architecture docs, etc.)
+- Changing any code, build scripts, or CI configuration
+
+## Decisions
+
+### 1. Single DEVELOPER.md file (not multiple docs files)
+
+All developer content goes into one top-level DEVELOPER.md rather than a `docs/` directory or separate CONTRIBUTING.md / BUILDING.md files. The total developer content is small enough (~80 lines) that splitting further would be unnecessary overhead. A single file at the repo root is immediately discoverable.
+
+**Alternative considered**: `docs/` directory with multiple files. Rejected because the content volume doesn't justify the structure, and root-level DEVELOPER.md is a well-known convention.
+
+### 2. Content split boundary
+
+Content stays in README.md if it's needed by someone who just wants to **run** kb. Content moves to DEVELOPER.md if it's only needed by someone who wants to **build, modify, or release** kb.
+
+Specifically moving to DEVELOPER.md:
+- "From source" subsections under both engine and client install
+- Entire "Building and releasing" section (release scripts, version checking, Docker image tags, registry overrides)
+- "Future: ROCm runtime migration" developer note
+
+Staying in README.md:
+- Architecture overview (helps users understand what they're running)
+- Pre-built image / release install instructions
+- Client configuration
+- Usage examples
+- Engine configuration table
+- Data portability
+- API reference
+- Claude Code skill reference
+
+### 3. Cross-reference approach
+
+A short note in README.md's Quick Start section pointing to DEVELOPER.md for building from source. No back-link needed from DEVELOPER.md since developers will naturally find README.md first.
+
+## Risks / Trade-offs
+
+- **[Stale cross-references]** If DEVELOPER.md sections are renamed, the link from README.md could break. Mitigation: link to the file, not to a specific anchor.
+- **[Discoverability]** Some users who want to build from source might miss DEVELOPER.md. Mitigation: explicit "See DEVELOPER.md" callout in the Quick Start section where "from source" instructions used to be.
@@ -0,0 +1,28 @@
+## Why
+
+README.md currently mixes user-facing content (what kb does, how to install and use it) with developer-facing content (building from source, releasing, Docker image internals, architecture deep-dives). Users looking for quick-start instructions have to scroll past release scripts and build commands. Developers looking for contribution/build info have to hunt through user docs. Splitting these into README.md (users) and DEVELOPER.md (developers/contributors) follows standard open-source convention and makes both audiences' experience cleaner.
+
+## What Changes
+
+- **Trim README.md** to focus on user-facing content: what kb is, how to install (from pre-built images/releases), how to configure, how to use, engine configuration reference, data portability, and API reference.
+- **Remove "from source" build instructions** from README.md (both engine and client sections).
+- **Remove "Building and releasing" section** from README.md entirely.
+- **Remove "Future: ROCm runtime migration"** developer note from README.md.
+- **Create DEVELOPER.md** containing: building engine from source, building client from source, release process (client and engine), Docker image details, version checking, ROCm migration notes, and any other contributor-oriented content.
+- **Add a link** from README.md to DEVELOPER.md for developers who want to build from source or contribute.
+
+## Capabilities
+
+### New Capabilities
+- `developer-docs`: Developer-facing documentation covering building from source, releasing, and contributing.
+
+### Modified Capabilities
+
+(none - no spec-level behavior changes, this is a documentation restructuring)
+
+## Impact
+
+- **Files modified**: `README.md` (trimmed)
+- **Files created**: `DEVELOPER.md` (new)
+- **No code changes**: purely documentation restructuring
+- **No API changes**: no functional impact
@@ -0,0 +1,63 @@
+## ADDED Requirements
+
+### Requirement: DEVELOPER.md exists at repo root
+The repository SHALL have a `DEVELOPER.md` file at the project root containing all developer-facing documentation.
+
+#### Scenario: File exists
+- **WHEN** a developer navigates to the repository root
+- **THEN** a `DEVELOPER.md` file SHALL be present
+
+### Requirement: DEVELOPER.md contains build-from-source instructions
+DEVELOPER.md SHALL contain instructions for building both the engine and client from source.
+
+#### Scenario: Engine build from source
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include instructions for starting the engine from source using compose files (both NVIDIA and ROCm)
+
+#### Scenario: Client build from source
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include instructions for building the client binary from source using `make build` and `make all`
+
+### Requirement: DEVELOPER.md contains release process
+DEVELOPER.md SHALL document the release process for both client and engine, including release scripts, version bumping, and Docker image tagging.
+
+#### Scenario: Client release documentation
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include `release-client.sh` usage with flag options (--gitea, --github, --minor, --no-increment, --dry-run)
+
+#### Scenario: Engine release documentation
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include `release-engine.sh` usage with flag options and Docker image tag conventions
+
+#### Scenario: Version checking
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include how to check client and engine versions
+
+### Requirement: DEVELOPER.md contains developer notes
+DEVELOPER.md SHALL include any forward-looking developer notes such as migration plans or technical debt items.
+
+#### Scenario: ROCm migration note
+- **WHEN** a developer reads DEVELOPER.md
+- **THEN** it SHALL include the ROCm runtime migration note about onnxruntime and MIGraphX
+
+### Requirement: README.md excludes developer-only content
+README.md SHALL NOT contain build-from-source instructions, release processes, or developer-only notes.
+
+#### Scenario: No from-source build steps in README
+- **WHEN** a user reads README.md
+- **THEN** there SHALL be no "From source" subsections under engine or client installation
+
+#### Scenario: No release section in README
+- **WHEN** a user reads README.md
+- **THEN** there SHALL be no "Building and releasing" section
+
+#### Scenario: No developer notes in README
+- **WHEN** a user reads README.md
+- **THEN** there SHALL be no "Future: ROCm runtime migration" section
+
+### Requirement: README.md cross-references DEVELOPER.md
+README.md SHALL include a link to DEVELOPER.md for users who want to build from source or contribute.
+
+#### Scenario: Developer link in quick start
+- **WHEN** a user reads the Quick Start section of README.md
+- **THEN** there SHALL be a note pointing to DEVELOPER.md for building from source
@@ -0,0 +1,17 @@
+## 1. Create DEVELOPER.md
+
+- [x] 1.1 Create DEVELOPER.md at repo root with engine build-from-source instructions (compose.nvidia.yaml and compose.rocm.yaml)
+- [x] 1.2 Add client build-from-source instructions (make build, make all)
+- [x] 1.3 Add "Building and releasing" section: release-client.sh and release-engine.sh usage with all flag options
+- [x] 1.4 Add version checking instructions (kb --version, curl status endpoint)
+- [x] 1.5 Add Docker image tag conventions and registry override documentation
+- [x] 1.6 Add "Future: ROCm runtime migration" developer note
+
+## 2. Trim README.md
+
+- [x] 2.1 Remove "From source (for development)" subsection under engine quick start
+- [x] 2.2 Remove "From source (for development)" subsection under client installation
+- [x] 2.3 Remove entire "Building and releasing" section
+- [x] 2.4 Remove "Future: ROCm runtime migration" section
+- [x] 2.5 Add cross-reference note to DEVELOPER.md in the Quick Start section for building from source
+- [x] 2.6 Move API reference section from README.md to DEVELOPER.md