opencode-kb-test

This repository is a small sandbox for testing OpenCode capabilities while managing a Markdown-based knowledge base.

The core idea is to keep the repo simple (plain .md files, no database) while still enabling useful workflows: writing notes, organizing topics, maintaining links, and evolving structure over time.

Goals

• Validate OpenCode workflows for creating, updating, and reorganizing Markdown knowledge base content.
• Exercise common maintenance tasks (indexing, link hygiene, deduplication, refactors).
• Keep the knowledge base readable in Git and easy to review in pull requests.

Non-goals

• No required static site generator.
• No proprietary or hosted knowledge base product.
• No strict schema beyond lightweight conventions.

Suggested Repository Layout

This repo starts intentionally minimal. As you add content, a practical layout is:

kb/                     # Knowledge base root
  _index.md             # Optional: landing page / table of contents
  topics/               # Broad categories (optional)
  how-to/               # Task-oriented docs (optional)
  reference/            # Facts, commands, APIs (optional)
  decisions/            # ADRs / architecture decisions (optional)
  templates/            # Reusable doc templates (optional)

If you already have a structure in mind, use it; the only strong recommendation is to keep KB content in a single top-level directory (for easy searching and tooling).

Writing Conventions (Lightweight)

• One topic per file.
• File names: kebab-case.md (stable URLs and clean diffs).
• Start each document with a single H1 title.
• Prefer relative links between documents (portable across forks/clones).

Optional metadata (only if it helps):

---
title: "Example Title"
tags: [opencode, kb]
created: 2026-01-21
updated: 2026-01-21
---

Typical Workflows

Add a new article

1. Create a new file under kb/.
2. Write a short intro paragraph (what this doc is for).
3. Add links to related docs.
4. Update kb/_index.md if you maintain a manual table of contents.

Search the knowledge base

From the repo root:

rg "your search term" kb

Refactor / reorganize

When you move files:

• Update inbound/outbound links.
• Keep redirects if you publish docs elsewhere (not required for a pure Git repo).
• Prefer smaller, focused commits so diffs stay reviewable.

Using OpenCode in This Repo

Examples of good tasks to run through OpenCode:

• "Create a new KB article about X and link it from the index."
• "Split this long doc into 3 smaller docs and fix the links."
• "Find duplicate notes about Y and consolidate them."
• "Standardize headings and add a short summary section to each doc in kb/reference/."

Status

This is a testbed repo. Expect conventions and structure to evolve.

License

Add a license if/when you plan to share this repository publicly.