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>
53 lines
2.8 KiB
Markdown
53 lines
2.8 KiB
Markdown
## 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.
|