steve
afbe270181
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>
2.8 KiB
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.