kb/openspec/changes/archive/2026-03-31-split-readme-developer-docs/proposal.md at main

steve/kb

Files

T

steve afbe270181 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

1.8 KiB

Raw Permalink Blame History

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

1.8 KiB Raw Permalink Blame History

Why