business-context-os

LLM wiki kit

First committed by walm00

Published in walm00/business-context-os. Publisher page

22 GitHub starsUpdated 2026-05-15

What it is

CLEAR Context OS is the maintenance layer your second brain never had: ownership boundaries enforced mechanically, staleness surfaced on a schedule, drift propagated across linked docs, a dispatcher that learns from your clicks. One source of truth per topic. Searchable. Task-aware.

— the description by walm00

AutoGineer overview, from the brain’s own files

CLEAR Context OS is a framework designed to solve the problem of silent context degradation in AI agents. By implementing a structured methodology called CLEAR (Contextual Ownership, Linking, Elimination, Alignment, Refinement), it provides a maintenance layer that manages knowledge through automated scheduling, ownership enforcement, and drift detection. It organizes information into specific zones—such as canonical data, wiki-based derivatives, and verbatim evidence—ensuring that agents always operate on the most accurate, source-of-truth-ranked information. The system includes a dispatcher for scheduled maintenance, a local dashboard for monitoring, and integration with Claude Code to facilitate onboarding and task-aware context retrieval.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

The system organizes information into a folder hierarchy where the path itself acts as a trust signal for the LLM. It uses a dispatcher to run scheduled maintenance jobs that check for staleness, propagate updates across linked documents, and audit content health. New information is ingested through a routing process that places content into specific zones: canonical data for facts, wiki pages for operational knowledge, and collections for legal evidence. The system learns from user interactions to suggest fixes and uses frontmatter metadata to allow agents to filter and retrieve information efficiently without full-text scanning.

Folders
Folder	Role	Files
.claude	agent-config	193
.github	agent-config	6
docs	docs	68

The agent reads

docs/_bcos-framework/guides/folder-conventions.md evidence: CLAUDE.md
docs/_inbox/ evidence: README.md

The agent writes

docs/_inbox/ evidence: CLAUDE.md

Requirements

Works with: Claude Code, OpenCode

Set it up

This brain runs code automatically: 5 hooks (claude-code), 1 script. Review .claude/settings.json, install.sh before opening the folder in Claude Code. No step below turns a hook on for you.
- .claude/settings.json: bash "$CLAUDE_PROJECT_DIR/.claude/hooks/auto_save_session.sh"
- .claude/settings.json: bash "$CLAUDE_PROJECT_DIR/.claude/hooks/precompact_save.sh"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_commit_context_check.py"
- install.sh: sh install.sh

Clone the repository at the commit AutoGineer scanned:

git clone https://github.com/walm00/business-context-os.git && cd business-context-os && git checkout 463568372f31f24fa6c01121c38f989845ca7c84

Claude Code reads CLAUDE.md from this folder automatically.
cd business-context-os && claude
AutoGineer scanned these files at commit 4635683.
First committed by walm00. Published in walm00/business-context-os. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

Automating the maintenance of project documentation and SOPs.
Providing AI agents with a reliable, freshness-aware knowledge base.
Managing ownership boundaries across large, multi-topic documentation sets.
Syncing and auditing context across linked documents to prevent drift.
Generating daily digests of system health and pending maintenance tasks.

“Install BCOS from https://github.com/walm00/business-context-os and walk me through onboarding.”: Claude clones the repository, sets up the environment, and guides the user through an interactive onboarding process to configure the context architecture.
“/context bundle market-report:write”: The agent retrieves a curated, freshness-aware package of context specifically relevant to writing a market report.
“Run the audit twice a week.”: The dispatcher updates the maintenance schedule to perform an audit of the knowledge base on a bi-weekly cadence.
“/wiki run https://stripe.com/docs/api”: The system fetches the URL, summarizes the content, and creates a cited wiki entry within the knowledge base.

Documentation by walm00

<h1 align="center">CLEAR Context OS</h1> Knowledge that maintains itself — so your AI doesn't act on what was true last month. <a href="#install">Install</a>  ·  <a href="#what-it-does">What it does</a>  ·  <a href="#the-wiki-zone">Wiki zone</a>  ·  <a href="#what-ships">What ships</a>  ·  <a href="docs/_bcos-framework/guides/getting-started.md">Getting Started</a> <img src="https://img.shields.io/badge/claude_code-ready-blueviolet" alt="Claude Code"> <img src="https://img.shields.io/badge/methodology-CLEAR-green" alt="CLEAR Methodology"> <img src="https://img.shields.io/badge/install-one_command-success" alt="One-command install"> <img src="https://img.shields.io/badge/skills-17-blue" alt="17 skills"> <img src="https://img.shields.io/badge/maintenance_jobs-12-orange" alt="12 maintenance jobs"> <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT">

Your AI had perfect context — two weeks ago. Then your strategy shifted, three meetings redefined priorities, and the docs you wrote on Monday are wrong by Friday. CLEAR Context OS is the maintenance layer your second brain never had: ownership boundaries enforced mechanically, staleness surfaced on a schedule, drift propagated across linked docs, a dispatcher that learns from your clicks. One source of truth per topic. Searchable. Task-aware. Never silently stale.

Install

Easiest — let Claude do it. Open Claude Code in any directory and paste:

"Install BCOS from https://github.com/walm00/business-context-os and walk me through onboarding."

Claude clones the repo, picks the right install path for your platform (Windows/macOS/Linux), runs setup, and steps straight into onboarding. No prereq checks to debug — if something's missing, Claude resolves it interactively.

Or manually, two commands:

curl -fsSL https://raw.githubusercontent.com/walm00/business-context-os/main/install.sh -o /tmp/bcos-install.sh
bash /tmp/bcos-install.sh

(Requires bash, curl, and tar on PATH — fine on macOS/Linux and on Windows under WSL or Git Bash. Two steps instead of a single bash <(curl …) pipe so Claude Code's permission gate auto-approves both commands — you don't need to drop out to a terminal.)

Drop anything you already have — SOPs, brand docs, meeting notes, exports — into docs/_inbox/ (skip if you're starting fresh). Then open Claude Code in that repo and say:

"Launch BCOS onboarding."

That's the only prompt you need. Onboarding inspects your inbox, scans the rest of the repo, asks one Q&A round, and proposes the architecture for review. Works the same whether the repo is fresh or already full of context.

From zero to running

  INSTALL  →  DISCOVER  →  ALIGN  →  SCHEDULE  →  RUNNING

#	Step	What happens
1	Install	One bash line drops the framework into any repo
2	Discover	Claude scans your repo + any MCP you've connected (Drive, Notion, Slack, Gmail, your CRM — whatever's wired in) for existing context, plus anything you've dropped into `docs/_inbox/`
3	Align	One Q&A round — project type, key sources, ownership boundaries. Architecture drafted for your review
4	Schedule	Pick maintenance cadence in plain English: "audit twice a week", "dispatcher at 08:30", "deep daydream off"
5	Running	Daily digest. Local dashboard. `/context bundle <task>` ready. Context compounds from here — the system maintains itself.

Simple, guided, automatic. Claude walks you through each step — you review, you decide. Nothing deleted along the way — originals preserved or archived, never silently overwritten.

What it does

Stops context rot in three ways:

	What it does
Organize	Every doc declares what it owns. CLEAR boundaries prevent the same fact living in 5 places.
Maintain	Scheduled jobs check freshness, surface stale docs, propagate updates across linked content.
Use	`/context search` and `/context bundle <task>` give Claude curated, freshness-aware, source-of-truth-ranked context for the job at hand.

The folder tells the LLM what to trust. Claude reads the path before the content: docs/*.md = canonical, _planned/ = not yet real, _archive/ = history, _inbox/ = unprocessed, _collections/ = verbatim evidence, _wiki/ = explanatory. The hierarchy is the trust signal — fewer tokens spent re-deciding, no chance of treating an archived draft as today's truth.

docs/
├── *.md                  ← canonical data points (one source of truth per topic)
├── document-index.md     ← auto-generated TOC
├── current-state.md      ← what's true right now + what changed recently
├── table-of-context.md   ← high-level cluster map for orientation
├── _inbox/               ← drop zone — Claude triages on demand
├── _planned/             ← polished ideas, not yet real
├── _archive/             ← superseded — kept, not deleted
├── _collections/         ← verbatim evidence (invoices, contracts, transcripts)
│   └── <type>/_manifest.md   (each collection has a manifest)
├── _wiki/                ← derivative knowledge (how-tos, source summaries)
│   ├── pages/            ← user-authored explainers
│   ├── source-summary/   ← external captures with citation banners
│   ├── raw/              ← original artifacts (PDFs, HTML)
│   └── queue.md          ← URLs awaiting fetch
└── _bcos-framework/      ← framework docs — never user content
    ├── architecture/     ← 12 zone + system architecture docs
    ├── methodology/      ← 5 CLEAR + ownership + standards docs
    ├── patterns/         ← 8 project-type starting templates
    └── templates/        ← 15 frontmatter / schema / starter files

The wiki zone

Inspired by Karpathy's LLM Wiki approach — give the LLM a wiki of your knowledge, the way you'd brief a smart new hire.

Save anything to the wiki, from anywhere:

/wiki run https://stripe.com/docs/api          ← fetch a URL, summarize, cite
/wiki create from /Users/me/Downloads/spec.pdf ← extract a PDF, link to the binary
/wiki promote docs/_inbox/meeting-notes.md     ← turn an inbox capture into a wiki page

The wiki holds how-tos, runbooks, glossaries, source summaries, post-mortems, decision logs — derivative knowledge that explains and supports your canonical data points. Every page cites what it builds on. Stale pages surface automatically when their sources advance.

Wiki content is searchable alongside the rest of your context:

/context search "stripe billing"       ← cross-zone search, ranked by source-of-truth
/context bundle market-report:write    ← curated bundle for a specific task

The dashboard

A local cockpit at http://127.0.0.1:8091 that shows your system at a glance — no third-party services, no telemetry, no logins.

Image: BCOS dashboard cockpit — knowledge system status, things waiting on you, maintenance routine

python .claude/scripts/bcos-dashboard/run.py

Surface	What you see
Cockpit	One-line status (healthy / N waiting / heads-up). Per-job dot strip for every maintenance job (core BCOS + wiki zone).
Update	"Run full sync" button → `update.py` + CLAUDE.md drift review + auto-commit + push, with a live log drawer.
Schedules (`/settings/schedules`)	Per-job preset buttons (`daily`, `mon_wed_fri`, `weekly_mon`, `off`) + the global auto-commit toggle + auto-fix whitelist. Saves directly to `schedule-config.json`.
Run history (`/settings/runs`)	Last 20 dispatcher runs with filter chips (job / verdict / trigger).
File health (`/settings/files`)	Frontmatter / cross-reference / staleness findings with one-click fixes.

The dashboard is read-mostly: data flows from the dispatcher's diary, the schedule config, and the canonical context index. Writes (mark-done, schedule preset, auto-commit toggle, file fix) go through dedicated POST endpoints.

Requirements

Claude Code (desktop app, CLI, or web)
Python 3.8+ on PATH
bash (default macOS bash 3.2 is fine)

Updating

python .claude/scripts/update.py

Refreshes framework files only — skills, hooks, scripts, templates. Your docs/ and .private/ are never touched.

Maintenance

One scheduled task per repo. The dispatcher reads schedule-config.json, runs the jobs due today, writes one consolidated digest at docs/_inbox/daily-digest.md, and surfaces findings as one-click cards in the dashboard.

Image: BCOS maintenance schedule dispatcher — daily, weekly, monthly jobs flowing into the daily digest and dashboard cards

You can tune any of it in plain English:

"Run the audit twice a week." · "Move dispatcher to 08:30." · "Turn off deep daydream."

The system learns from your clicks. After three consistent uses of the same fix, the dashboard pre-selects it as a "✨ suggested" action — you accept or reject. Reversals trigger an automatic safety brake.

CLEAR — the methodology

Five principles, one rule each:

C — Contextual Ownership · one document owns each topic. No duplicates.
L — Linking · reference sources; don't copy them.
E — Elimination · consolidate; don't keep two versions.
A — Alignment · context that doesn't support decisions doesn't belong.
R — Refinement · structured maintenance, not ad-hoc fixes.

The whole framework is the mechanical implementation of these five rules.

What ships

Everything below installs as one repo drop-in. No third-party services, no logins, no telemetry — all state lives in your .claude/ and docs/ folders.

Layer	Count	Examples
Skills (chat-invokable via slash command)	17	`clear-planner` · `bcos-wiki` · `context-routing` · `context-audit` · `context-ingest` · `daydream` · `learning` · `schedule-tune` · `lessons-consolidate` · `ecosystem-manager`
Sub-agents (delegated bounded tasks)	3	`wiki-fetch` · `explore` · plus one optional
Scripts (mechanical Python)	46	`lifecycle_sweep` · `run_wiki_` (5) · `cmd_wiki_` (7) · `auto_fix_audit` · `bcos_inventory` · `digest_sidecar` · `record_resolution`
Hooks (auto-validation on edit)	4	post-edit frontmatter check · post-commit context check · pre-compact save · auto-save session
Maintenance jobs (scheduled, one dispatcher)	12	`index-health` · `audit-inbox` · `daydream-lessons` · `daydream-deep` · `architecture-review` · `auto-fix-audit` · `lifecycle-sweep` · `wiki-stale-propagation` · `wiki-source-refresh` · `wiki-graveyard` · `wiki-coverage-audit` · `wiki-canonical-drift`
Auto-fix IDs (silent dispatcher fixes)	12	`missing-last-updated` · `eof-newline` · `frontmatter-field-order` · `wiki-mark-queue-ingested` · `wiki-archive-expired-post-mortem`
Architecture docs	12	`wiki-zone.md` · `lifecycle-routing.md` · `typed-events.md` · `context-zones.md` · `content-routing.md` · `wiki-headless-scripts.md`
Methodology docs	5	CLEAR principles · context architecture · decision framework · document standards · ownership specification
Project patterns (starting templates by project type)	8	client-project · gtm · marketing · operational · product-development · product-service · internal-tool-app · internal-tool-automation
Templates (frontmatter, schema, starters)	15	data-point · cluster · current-state · table-of-context · wiki-schema · wiki-config · session-diary-starter

Every script and skill is documented at the source. Every job has a reference doc under .claude/skills/schedule-dispatcher/references/job-*.md. Every typed-event finding maps to a renderer in the dashboard cockpit. Adding a new check means dropping a cmd_*.py or run_*.py, registering it in one map, and the dashboard picks it up.

Contributing

Contributions welcome — open an issue or submit a PR targeting the dev branch. CI runs frontmatter, reference, and ecosystem-integration checks on every PR.

The fastest contribution path is lessons learned. As you use the system it captures insights; if you find one universal, contribute it back.

Origin

Built by Guntis Coders after two years of operating context systems in production. The CLEAR methodology emerged from a practical problem: AI context degrades silently, and no amount of one-time documentation prevents it. The solution required a system — ownership boundaries, automated maintenance, self-learning, and structured reflection.

Background: What is the Table of Contexts and why does it matter.

License

MIT

docs/_bcos-framework/architecture/collections-zone.md

Collections Zone Architecture

How docs/_collections/ works in CLEAR Context OS — what it holds, why files there are immutable, how the manifest pattern makes binary cargo first-class evidence, how its vocabularies grow with the business, and how it stays distinct from _wiki/, _inbox/, and active data points.

For the sibling zone mechanics see wiki-zone.md and content-routing.md. For the philosophical placement of zones see system-design.md.

Net summary in one line: files in _collections/ are immutable evidence — invoices, signed contracts, brand kits, transcripts, exports. We manifest the directory, not the files: each subdirectory carries a required _manifest.md with one row per file, BCOS-aligned frontmatter, and bidirectional links to active data points. A schema-driven .schema.yml registry defines collection sub-types and their required manifest columns, so adding a new collection category is one edit, not five.

Why a Collections Zone Exists

BCOS already has homes for truth (docs/*.md data points), explanation (docs/_wiki/), future state (_planned/), and triage (_inbox/). What's missing is a home for artifacts the user receives or generates that should not be paraphrased:

An invoice PDF — paraphrasing it loses the signature, the line items, the amount in the original currency
A signed contract — the file IS the legal instrument
A brand kit zip — the assets ARE the brand
A call transcript — the words spoken are the evidence
A monthly Stripe export, a Salesforce dump, a downloaded report — the file IS the source of record

Editing these files corrupts evidence. Paraphrasing them into a data point loses fidelity. They need a zone with three properties: (1) immutable — the framework never rewrites these files; (2) inventoried — Claude knows what's there without opening every file; (3) linked — every artifact ties back to the data points it provides evidence for.

That's _collections/.

The Immutability Constraint — and Why It Forces a Pattern

You can't put YAML frontmatter inside a PDF. You can't add a version: line to a docx. You can't bump last-updated on a zipped brand kit. The metadata has to live somewhere adjacent to the file, not inside it.

Pin-llm-wiki faces the same constraint with its raw/<type>/ captures (verbatim, never edited) and solves it with a per-directory README.md that holds the metadata table. We adopt the same pattern, generalize it, and require it.

The rule: manifest the directory, don't try to manifest the files.

Folder Layout

docs/_collections/
├── .schema.yml                         # Vocabulary registry — see "Schema and Governance"
├── README.md                           # Zone overview (auto-maintained)
│
├── invoices/                           # manifest-schema: invoices
│   ├── _manifest.md                    # required — one row per file
│   ├── 2026-04-08_acme-q2.pdf
│   ├── 2026-03-12_globex-march.pdf
│   └── .archive/                       # soft-deleted artifacts (see "Soft-Delete Pattern")
│       └── 2024-old-format.pdf
│
├── contracts/                          # manifest-schema: contracts
│   ├── _manifest.md
│   ├── 2026-04-08_acme-msa.pdf
│   ├── 2026-04-08_acme-msa.meta.md     # OPTIONAL sidecar — rich metadata
│   ├── 2026-03-15_globex-nda.pdf
│   └── .archive/
│
├── brand-kits/                         # manifest-schema: brand-kits
│   ├── _manifest.md
│   ├── brand-kit-v2.0.zip
│   └── brand-kit-v2.0.meta.md          # extracted color codes, font names
│
├── call-transcripts/                   # manifest-schema: call-transcripts
│   ├── _manifest.md
│   └── 2026-04-12_acme-discovery.md
│
├── statements/                         # manifest-schema: statements
│   ├── _manifest.md
│   └── 2026-Q1_stripe-export.csv
│
└── wiki-source-docs/                   # manifest-schema: custom — files referenced by _wiki/ pages (Path B in wiki-zone)
    ├── _manifest.md
    └── 2026-04-15_competitor-analysis.pdf

Three artifact types, three handling rules:

Artifact form	Manifest treatment	Sidecar?	Reason
Binary (PDF, .docx, .zip, .png)	Required row	Optional — when row can't carry the metadata	We can't put frontmatter in a PDF
Plain text/markdown (transcripts, exports)	Required row	Rare — only when extracted facts deserve structure	The file itself can be glob-searched
Structured data (CSV, JSON exports)	Required row	Optional — when extracted KPIs deserve their own page	The file is machine-readable

The `_manifest.md` Schema

One per subdirectory. Required. The manifest is the awareness surface — Claude reads it at session start and during retrieval; it never opens the underlying PDFs unless a query specifically demands it.

Frontmatter (BCOS-aligned)

---
type: collection-manifest
collection: contracts                 # subdirectory name
manifest-schema: contracts            # contracts | invoices | brand-kits | call-transcripts | statements | reports | custom
version: 1.4.0                        # bumped on every row change
created: 2026-01-15
last-updated: 2026-04-30
last-scanned: 2026-04-30              # auto-updated by collections-scan
file-count: 12                        # auto-maintained
owner: gunti
status: active

cluster: partnerships                 # primary cluster (single, BCOS convention)
related-clusters:                     # optional cross-cutting clusters
  - vendor-relationships

# Aggregated cross-zone references (graph-ready)
related-data-points:                  # data points that any row in this manifest cites
  - partnerships.md
  - vendor-relationships.md
---

Body — the file table

The columns vary by manifest-schema. Pre-defined schemas have known required columns; lint enforces them.

Schema: contracts

# Contracts — manifest

| File | Counterparty | Type | Signed | Expires | Status | Related data point |
|------|--------------|------|--------|---------|--------|--------------------|
| 2026-04-08_acme-msa.pdf | Acme Corp | MSA | 2026-04-08 | 2028-04-08 | active | [partnerships](../../partnerships.md) |
| 2026-03-15_globex-nda.pdf | Globex | NDA | 2026-03-15 | perpetual | active | [partnerships](../../partnerships.md) |
| 2025-09-01_initech-saas.pdf | Initech | SaaS | 2025-09-01 | 2026-09-01 | **expiring-soon** | [vendor-relationships](../../vendor-relationships.md) |

Schema: invoices

Schema: brand-kits

Schema: call-transcripts

Schema: statements

Schema: reports

Derived analytical reports — produced by an internal pipeline (financial audits, competitive-intel exports, customer-discovery rollups). The manifest row is the awareness surface; pair it with a .meta.md sidecar (see "Derived-Report Sidecar" below) when the report has key numbers worth ranking against value-lookup queries.

File	Period	Report type	Audience	Run date	Related data point
2026-04-30_q1-revenue.xlsx	2026-Q1	Revenue rollup	Investors	2026-04-30	revenue-model
2026-02-15_competitive-landscape.html	2026-02	Competitive scan	Internal	2026-02-15	competitive-positioning

Schema: custom

User-defined columns. Lint reports schema as INFO ("custom schema in use, no column-level validation"). All other manifest checks still apply (untracked, orphan, expiry).

The full enumeration of available manifest-schema values lives in _collections/.schema.yml (see "Schema and Governance" below). New schemas are added there, not by editing this document.

Why markdown links instead of `[[wikilinks]]`

Wikilinks [[slug]] are reserved for _wiki/ ↔ _wiki/ refs (the wiki's internal graph). Cross-zone references — collection → data point, wiki → data point, wiki → collection — use standard markdown links so the dependency direction is unambiguous and doc-lint resolves them with the existing path-checking.

Sidecar `.meta.md` — When the Row Isn't Enough

Default: a manifest row covers the file. Sidecar only when the artifact deserves richer metadata the row can't fit:

A 50-page MSA with 5 key clauses worth indexing
A brand kit with extracted color codes (#1a73e8), font names, asset inventory
A call transcript with a structured "Decisions" / "Action Items" extraction

# 2026-04-08_acme-msa.meta.md (sits next to 2026-04-08_acme-msa.pdf)
---
type: collection-sidecar
collection: contracts
artifact-file: 2026-04-08_acme-msa.pdf
version: 1.0.0
created: 2026-04-09
last-updated: 2026-04-09
owner: gunti
status: active

cluster: partnerships
builds-on:                              # data points this artifact provides evidence for
  - partnerships.md
  - pricing-model.md

# Sidecar-specific
extracted-on: 2026-04-09
extraction-method: human                # human | llm | mixed
key-fields:
  counterparty: Acme Corp
  effective-date: 2026-04-08
  expiry-date: 2028-04-08
  governing-law: Delaware
  termination-clause: section 12.3
  payment-terms: net-30
---

## Key clauses

### Section 4 — Service levels
99.5% uptime SLA, 4-hour response time...

### Section 12.3 — Termination
Either party may terminate with 30-day written notice...

Sidecar discipline:

Sidecar is hand-written or LLM-extracted on ingest, then human-reviewed.
Sidecar follows BCOS frontmatter rules (versioned, owned, status).
Sidecar can be edited independently; the artifact PDF stays immutable.
If a sidecar contradicts the artifact (someone mis-extracted a date), the artifact wins — sidecar is a derived view, not the source.

Derived-Report Sidecar

Derived reports (Excel/CSV/HTML produced by an internal pipeline) are a recurring artifact category — financial audits, competitive-intel scans, customer-discovery rollups, product-metrics summaries. They benefit from a sidecar that names the period, the freshness window, and the key fields the resolver should rank against value-lookup:answer queries.

# 2026-04-30_q1-revenue.meta.md (sits next to 2026-04-30_q1-revenue.xlsx)
---
type: collection-sidecar
collection: reports
artifact-file: 2026-04-30_q1-revenue.xlsx
version: 1.0.0
created: 2026-04-30
last-updated: 2026-04-30
owner: gunti
status: active

cluster: revenue
builds-on:                              # data points this evidence supports
  - revenue-model.md
  - customer-base.md

# Derived-report sidecar fields
period: "2026-Q1"
generated-from: docs/_collections/raw-data/q1-2026-stripe-export.csv
generation-date: 2026-04-30
generation-method: scripts/generate_revenue_report.py
freshness: fresh                        # fresh | stale | regenerate-now
freshness-window: 90d                   # past this, retrieval flags as stale
extracted-on: 2026-04-30
extraction-method: human                # human | llm | mixed

key-fields:
  total-mrr: 42000
  largest-customer: Acme Corp
  largest-customer-mrr: 8500
  new-customers-q1: 7
  churned-customers-q1: 2
---

## Q1 2026 — Revenue summary

(Prose context distilled from the xlsx — anchors for value-shape questions.)

Field reference:

Field	Purpose
`period`	Time window the report covers — quarter, month, audit span. Free-form string; the resolver does not parse semantics.
`generated-from`	Repo-relative path to the raw input. Lets the next pipeline run identify what to re-process.
`generation-date`	When this output was produced. Compared against `freshness-window` to decide regenerate-now.
`generation-method`	Pipeline script or process. Lets a maintainer find how to regenerate without reading the manifest.
`freshness`	Author's current verdict: `fresh` / `stale` / `regenerate-now`. The freshness-window expiry is mechanical; this field is the human override.
`freshness-window`	Duration after which retrieval flags this sidecar as stale (`Nd`, `Nw`, `Nm`).
`key-fields`	Domain-specific extracted values. The framework specifies the shape (map of name → value), not the vocabulary — finance uses `total-spend-eur`, revenue uses `total-mrr`, competitive intel uses `top-3-competitors`, etc.

Lifecycle:

The same pipeline that produces the report writes the sidecar (or a follow-up extract_keyfields.py step).
When freshness-window expires, the next pipeline run regenerates the sidecar with updated key-fields:.
collections-scan may surface freshness: stale or window-expired sidecars in its log.
Authors who want to flag a stale claim that still references this sidecar use stale-claims: on the canonical doc (see document-standards.md).

Why this matters: the value-lookup:answer task profile (catalog: _context.task-profiles.yml.tmpl) ranks collection-sidecar above collection-manifest, collection-artifact, and active data points — precisely because the sidecar's key-fields: is evidence-extracted, fresh, and structured for measurement-shape questions. Without the sidecar, the resolver falls back to canonical taxonomy, which is the wrong answer for "how much / when / who / top-N" queries.

Naming Convention — Soft, Scanned, Not Enforced

Adopt pin-llm-wiki's YYYY-MM-DD_<descriptor>.<ext> as a suggestion. Three rules:

Never rename user files. If someone uploads Acme Q3 Review.pdf, that's the filename. Don't auto-rename to 2026-04-08_acme-q3-review.pdf — you'll break external references that point to the original name.
Soft-flag inconsistency. collections-scan reports filename-convention violations as INFO, never WARN.
Encourage forward. New uploads through context-ingest are gently nudged toward the convention via AskUserQuestion: "Filename violates convention. Rename to 2026-04-08_acme-q3-review.pdf?" with options Rename / Keep as-is / Always keep as-is for this collection.

Filename length under 100 characters to avoid cross-platform issues (already in current content-routing.md Path 5 — keeping).

Soft-Delete Pattern

Ported from pin-llm-wiki's wiki/.archive/ mechanism with a dangling-reference scan.

When /collection archive <file> runs:

File moves from _collections/<type>/<file> → _collections/<type>/.archive/<file>
Manifest row updates: status: archived, append archived: <date> column (manifest gets one more column the first time something is archived; lint accepts column variance for archive-related fields)
Dangling-reference scan runs across docs/*.md, _wiki/**/*.md, and other manifest tables for any markdown link or sidecar reference to the archived file. Findings are reported, not auto-fixed — the user decides whether to update references, archive the citing doc, or restore the artifact.
Sidecar moves with the artifact if one exists.

Restore: /collection restore <file> reverses the move and resets manifest row status: active.

Hard-delete: never automated. Files in .archive/ stay until a human deletes via OS file ops + manually edits the manifest. The framework treats .archive/ as cold storage.

The `collections-scan` Job

New scheduled job, weekly cadence by default. Ten checks.

#	Detection	Severity	What gets reported
1	File on disk, no manifest row	WARN	"Untracked file: `_collections/invoices/q2-2026.pdf` — add manifest row"
2	Manifest row, file missing on disk	ERROR	"Orphan manifest row: `2025-deleted-doc.pdf`"
3	Sidecar `.meta.md` references missing artifact	ERROR	Same orphan logic, with sidecar path
4	`status: active` AND `expires < today + 30d`	WARN	"Expiring soon: 2 contracts" + list
5	`status: active` AND `expires < today`	ERROR	"Expired but still marked active"
6	Row with empty `Related data point` column	INFO	"N files unlinked to active context"
7	Filename violates suggested convention	INFO	Soft nudge only
8	Subdirectory >20 files but no `_manifest.md`	WARN	"Manifest required"
9	Manifest `manifest-schema` doesn't match required columns	ERROR	"Missing required column: `Counterparty`"
10	`Related data point` link resolves to a renamed/archived data point	ERROR	"Broken link: `[partnerships](...)` no longer exists"

Auto-fixes (whitelisted):

Update last-scanned: <today> in manifest frontmatter on every run
Update file-count: <n> in manifest frontmatter
Move row status from active → expiring-soon when within 30d of expiry
Move row status from expiring-soon/active → expired when past expiry

Wired into .claude/quality/schedule-config.json:

{
  "jobs": {
    "collections-scan": {
      "enabled": true,
      "schedule": "weekly",
      "_about": "Scan all _collections/<type>/ for manifest consistency, untracked files, orphans, expiry, and broken cross-zone links. Auto-fixes: last-scanned, file-count, derived status transitions."
    }
  },
  "auto_fix": {
    "whitelist": [
      "collections-update-last-scanned",
      "collections-update-file-count",
      "collections-mark-expiring-soon",
      "collections-mark-expired"
    ]
  }
}

Wake-Up Awareness

Generated into docs/.wake-up-context.md (the ~200-token snapshot Claude reads at session start).

The wake-up generator (python .claude/scripts/generate_wakeup_context.py) reads each _manifest.md frontmatter — file-count, status counts — and emits one line per collection:

Collections: 47 invoices, 3 brand kits, 12 contracts (1 expiring soon, 0 expired)

This is the equivalent of pin-llm-wiki's wiki/index.md "N sources ingested." Claude now knows, in one line, what evidence exists without scanning the directories.

Quarterly Coverage Audit (daydream-adjacent)

Folded into the existing daydream skill's quarterly run, or as a standalone collections-coverage job:

Question: "Which active data points have collection evidence but no link, or vice versa?"

Detection examples:

business-model.md exists but no invoice in _collections/invoices/ cites it as Related data point → are invoices being captured at all?
12 contracts in _collections/contracts/ exist but no partnerships.md data point → coverage gap (suggest creating one)
target-audience.md exists but no call transcript in _collections/call-transcripts/ cites it → are we capturing customer conversations?

This applies BCOS's compounding rule to evidence: a new collection item should prompt "does this evidence any data point? Should one exist if not?" and an active data point should prompt "is there evidence we should be linking?"

Integration with `context-ingest` (Path 5 extension)

context-ingest Path 5 (Collection) currently routes bulk files to _collections/<type>/. Extend with manifest discipline:

On each Path 5 routing:

Confirm or pick the <type> subdirectory (existing behavior)
Confirm or pick the filename convention (new — AskUserQuestion: rename to convention / keep as-is)
Move the file into the subdirectory
Append a manifest row — AskUserQuestion-driven for the schema-required columns (e.g., contracts: counterparty, type, signed, expires)
Prompt for Related data point — AskUserQuestion lists candidate data points (top 3 by cluster match) + "create new" + "leave empty for now"
Optionally prompt for sidecar — only when artifact is binary and large (>10 pages PDF, multi-asset zip, etc.): "This artifact looks substantial. Create a sidecar .meta.md?"

The manifest row + optional sidecar happen in the same ingest turn as the file move. No silent uploads.

Integration with `_wiki/`

_collections/ and _wiki/ are complementary:

Direction	What happens
Wiki ingest captures a local file or URL	Capture stays inside `_wiki/raw/<type>/`; the authored page lands in `_wiki/pages/` or `_wiki/source-summary/` and cites canonical data points with `builds-on:`
Wiki page references an existing collection artifact	Markdown link from wiki body: `see [Acme MSA](../../_collections/contracts/2026-04-08_acme-msa.pdf)` — `wiki-link-check` verifies it resolves
User wants the source file stored as standalone evidence	Run an explicit collection operation; add the file to `_collections/<type>/` with a manifest row, then link from the wiki page
Collection artifact archived	Dangling-ref scan finds wiki pages citing it → reported in collections-scan output → user decides whether to update wiki, archive wiki page, or restore artifact
Collections-scan finds an unlinked artifact	INFO finding can be paired with `coverage-gap` (wiki check) — "this artifact has no link from data points OR wiki — should one exist?"

Boundary rule: Wiki ingest does not implicitly write to _collections/. _collections/ is for user-owned evidence with value independent of a wiki page. _wiki/raw/ is for source captures created by wiki workflows. If the same file deserves both treatment paths, do them as two explicit operations so the user can see the evidence decision.

Naming alignment: _wiki/raw/<type>/ previously used README.md (pin-llm-wiki native). For consistency across zones, both rename to _manifest.md. This is a single search-and-replace in the adopted pin-llm-wiki skill.

Future RAG / Vector / Knowledge-Graph Compatibility

The collections zone becomes the evidence layer in a future RAG/graph stack. The design choices that make it ready:

Graph readiness

Source	Edge type	Direction	What populates
Manifest row `Related data point` column	`EVIDENCES`	artifact → data point	One per row
Sidecar `builds-on:` frontmatter	`EVIDENCES`	artifact → data point	One per data point
Manifest frontmatter `cluster:` + `related-clusters:`	`BELONGS_TO_CLUSTER`	manifest → cluster	One per cluster
Wiki page markdown link to artifact	`CITES_EVIDENCE`	wiki page → artifact	Resolved at lint time
Sidecar `key-fields:`	Node attributes	—	Searchable structured properties

A graph generator can walk _collections/<type>/_manifest.md + sidecar frontmatter and emit nodes (artifacts) + edges (artifact ↔ data point ↔ cluster ↔ wiki page). Combined with the wiki graph and the data-point graph, this is one connected business-context graph.

Retrieval readiness

For RAG over collections:

Binary files (PDF, docx) need extraction at index time — but the manifest row + sidecar .meta.md are already structured retrieval targets. Retrieval can return "manifest row + sidecar key-fields" without ever opening the PDF.
Text files (transcripts, exports) are directly indexable. The manifest row + filename are retrieval anchors.
Provenance for any retrieved chunk: chunk → file → manifest row → cluster → data point. Always traceable.

Embedding-update logic

File added → embed only the manifest row + sidecar (binary) or full content + manifest row (text)
File archived → invalidate file's embeddings; update graph edges
Sidecar updated → re-embed sidecar; manifest row unchanged unless table changed
Manifest schema upgrade (e.g., new column) → re-embed table only

What's deliberately NOT pre-built

We don't add explicit chunking markers, pre-extracted PDF text, or a graph-store schema now. The structural choices today (one manifest per directory, sidecars with frontmatter, kebab cross-zone links) carry the cost; the retrieval/embedding layer slots in later without re-formatting.

Schema and Governance

Vocabularies in _collections/ should grow with the business, not be chiseled in stone. The collections zone exposes its vocabulary via a single registry file, _collections/.schema.yml, that drives manifest validation, lint, and tooling. Every collection sub-type, every required-column list, every naming convention lives in one place. Schema-versioned. Migrating between versions is a defined operation (parallel to _wiki/.schema.yml — see wiki-zone.md "Schema and Governance").

`_collections/.schema.yml` registry

schema-version: 1
last-updated: 2026-04-30
last-migrated: null

manifest-schemas:
  invoices:
    description: "Invoices issued or received"
    required-columns: [File, Client, Amount, Currency, Issued, Paid, "Related data point"]
    file-naming-convention: "YYYY-MM-DD_<client>-<descriptor>.<ext>"
  contracts:
    description: "Signed agreements (MSA, NDA, SaaS)"
    required-columns: [File, Counterparty, Type, Signed, Expires, Status, "Related data point"]
    expiry-warning-days: 30
    auto-status-transitions: true     # active → expiring-soon → expired (managed by collections-scan)
  brand-kits:
    description: "Brand asset bundles"
    required-columns: [File, Version, "Asset count", Formats, "Valid from", "Related data point"]
  call-transcripts:
    description: "Recorded customer or partner conversations"
    required-columns: [File, Date, Participants, Topics, Outcome, "Related data point"]
  statements:
    description: "Financial / system exports (Stripe, Salesforce, etc.)"
    required-columns: [File, Period, Source, "Key numbers", "Related data point"]
  reports:
    description: "Derived analytical reports (Excel/CSV/HTML produced by an internal pipeline). Often paired with a `.meta.md` sidecar carrying period, freshness window, and extracted key-fields."
    required-columns: [File, Period, "Report type", Audience, "Run date", "Related data point"]
    file-naming-convention: "YYYY-MM-DD_<report-slug>.<ext>"
  custom:
    description: "User-defined; only base validation applies"
    required-columns: [File, "Related data point"]

statuses:
  - active
  - expiring-soon                     # auto-set when within expiry-warning-days
  - expired                           # auto-set when past expires
  - archived                          # soft-deleted to .archive/
  - historical                        # kept for reference, not actively used

# Cluster vocabulary inherits from BCOS (single source of truth)
cluster-source: docs/document-index.md
allow-cluster-not-in-index: false

# What `bcos init` should scaffold in a new repo
bootstrap-defaults:
  schemas: [custom]                   # start minimal; add specific schemas as collections grow
  note: "Start minimal. Add manifest-schemas as you discover real artifact categories. The 'custom' schema covers anything that doesn't fit a registered type."

Governance operations

Command	What it does
`/collection schema list`	Show current vocabulary (read-only)
`/collection schema add <schema-name>`	`AskUserQuestion`-driven: add manifest-schema with required-columns, naming-convention, optional expiry semantics
`/collection schema rename <from> <to>`	Migrate every manifest declaring `manifest-schema: <from>`; record in collections log
`/collection schema retire <schema-name>`	Mark deprecated; lint existing manifests with migration hint
`/collection schema validate`	Walk every `_manifest.md`; verify columns and statuses against schema
`/collection schema migrate <from> <to>`	Versioned migration with dry-run diff

Bootstrap behavior on `bcos init` in a new repo

_collections/.schema.yml is scaffolded with only the custom schema — no upfront speculation about whether the user will have invoices, contracts, etc.
First time context-ingest Path 5 routes to a new collection sub-type, it offers AskUserQuestion: "This collection looks like contracts. Add contracts as a registered manifest-schema, or use custom?"
Real-usage drives schema growth.

Same pattern across BCOS

The schema-driven principle applies symmetrically:

_wiki/.schema.yml — page-types, statuses, detail-levels, provenance-kinds, forbidden-builds-on-paths
_collections/.schema.yml — manifest-schemas, statuses, cluster-source
.claude/quality/lint-checks.json — registry of lint check IDs
.claude/quality/schedule-config.json — scheduled jobs with required _about field

The principle: adding a category should be one edit, not five.

Distinctions — Quick Reference

Looks like…	But is actually…	Decision rule
A wiki page	A sidecar	Does it sit next to a binary file with the same root? Sidecar.
A sidecar	A wiki page	Does it explain how to do something? Wiki. Does it just summarize one artifact's contents? Sidecar.
A data point	A sidecar	Does it assert canonical truth about the business? Data point. Is it derivative of one specific artifact? Sidecar.
A manifest	An index	Is it required and machine-validated? Manifest. Is it optional and human-curated? Index. (Manifests subsume the prior optional `_index.md` concept.)
`_collections/`	`_inbox/`	Is the file the truth (artifact)? Collections. Is it raw text awaiting triage? Inbox.
`_collections/`	`_wiki/raw/`	Is it user-uploaded evidence? Collections. Is it bot-generated capture (URL fetch)? Wiki raw. (Both use `_manifest.md`.)

Adoption Plan

1. Documentation updates

✅ CLAUDE.md — _collections/ row updated to flag manifest requirement (this turn)
✅ folder-conventions.md — _collections/ row updated to mention manifest (this turn)
✅ content-routing.md Path 5 — promote _index.md from optional to required, rename to _manifest.md, add expiry/sidecar fields (this turn)
This document (collections-zone.md) becomes the authoritative reference

2. Schema templates (next concrete step):

templates/_manifest.md.tmpl (per manifest-schema: contracts, invoices, brand-kits, call-transcripts, statements, custom)
templates/<artifact>.meta.md.tmpl (sidecar template)

3. Lint script:

.claude/scripts/collections_scan.py — implements the 10 checks above
Wired into .claude/quality/schedule-config.json per the JSON above
Returns findings in the standard dispatcher format

4. context-ingest extension:

Path 5 routing learns the new AskUserQuestion-driven manifest-row authoring
Filename-convention nudge becomes a structured option

5. Wake-up generator extension:

generate_wakeup_context.py reads each _manifest.md frontmatter
Emits one-line collection summary in the wake-up snapshot

6. Daydream extension:

Quarterly coverage audit added to daydream skill or as standalone collections-coverage job

7. _wiki/ zone alignment:

Rename _wiki/raw/<type>/README.md → _wiki/raw/<type>/_manifest.md for cross-zone consistency
Update wiki-zone.md adoption plan with this rename

Out of scope for v1:

PDF text extraction at scan time (deferred to RAG layer)
Auto-population of sidecar key-fields via LLM extraction (manual/prompted only)
Graph export to vector store (deferred to RAG layer)

Advantages

Prevents context rot by surfacing stale information on a configurable schedule. evidence: README.md
Enforces ownership boundaries to ensure one source of truth per topic. evidence: README.md
Reduces token usage by providing a structured index that avoids redundant scanning. evidence: CLAUDE.md
Enables task-aware context retrieval through curated bundles. evidence: README.md

Limitations

Requires adherence to a specific folder structure and frontmatter schema to function correctly. evidence: README.md
Maintenance jobs and dispatcher functionality rely on Python and bash being available on the host system. evidence: README.md

Security

Risk level: Medium risk

This brain runs

Agent instructions that run or fetch something (170)

.claude/agents/wiki-fetch/AGENT.md: A 100k-token URL fetched into the main thread by `/wiki run` saturates the context window before a single page lands.
.claude/agents/wiki-fetch/AGENT.md: | Calling skill | Subcommand | Trigger | |---|---|---| | `bcos-wiki` | `run` Pass 1 | Each URL in the queue → one `wiki-fetch` invocation | | `bcos-wiki` | `refresh` full-tier | Source-summary past `stale_threshold_days` and HEAD signals changed | | `bcos-wiki` | `promote` (Path B) | S …[+132 chars] · uses the network
.claude/agents/wiki-fetch/AGENT.md: The cumulative budget guard ([`_wiki_budget.decide_dispatch_strategy`](../../scripts/_wiki_budget.py)) decides whether N sub-agents run in parallel or serial — `parallel` when projected cumulative tokens stay ≤ 80% of the main context limit;
.claude/agents/wiki-fetch/AGENT.md: queue an explicit retry tag for next run | | `error.kind: fetch-error` | 4xx/5xx from upstream | Surface to user;
.claude/agents/wiki-fetch/AGENT.md: `python .claude/scripts/test_wiki_fetch.py` — asserts this AGENT.md declares the documented input kinds and output fields, that the 4000-token cap is stated, that calling-skill docs reference both `wiki-fetch` and the Task tool, and that the result-schema validator + cumulative budget g …[+47 chars]
.claude/skills/bcos-wiki/SKILL.md: **`/wiki`** with subcommands: `init`, `init --defaults`, `run`, `queue`, `promote`, `create`, `review`, `archive`, `refresh`, `lint`, `remove`, `schema`, `search`
.claude/skills/bcos-wiki/SKILL.md: "Run the wiki refresh"
.claude/skills/bcos-wiki/SKILL.md: | | `run [<url>]` | implemented | P3 | Path A: batch (no arg) processes all `## Pending` queue items;
.claude/skills/bcos-wiki/SKILL.md: single (with URL) auto-queues + ingests | | `queue <url> [tags]` | implemented | P3 | Append URL to `## Pending` of `queue.md` without fetching | | `ingest` | shared protocol | P3 | Internal — called by `run`/`promote`/`create`;
.claude/skills/bcos-wiki/SKILL.md: optionally re-pull `builds-on` data points to verify | | `archive <slug>` | implemented | P3 | Soft-delete to `_wiki/.archive/` with dangling-reference scan | | `refresh <slug>` | implemented | P3 | Path A: re-fetch a `source-summary` page (refresh-must-rediscover applies, D-05 two-tie …[+470 chars]
.claude/skills/bcos-wiki/SKILL.md: `run` → `run.md`
.claude/skills/bcos-wiki/SKILL.md: Run `/wiki init` first."* and exit.
.claude/skills/bcos-wiki/SKILL.md: | Choice | Behavior | |---|---| | Init with defaults + proceed | Run `.claude/scripts/cmd_wiki_init.py` (or equivalent `ensure_wiki_zone.py` call).
.claude/skills/bcos-wiki/SKILL.md: Then resume the original subcommand (`create from`, `promote`, `run`, etc.) as if the Guard had passed.
.claude/skills/bcos-wiki/SKILL.md: | | Full interview + proceed | Read `init.md` and run the 6-question interactive scaffold.
.claude/skills/bcos-wiki/SKILL.md: The dispatched subcommand files (`create.md`, `promote.md`, `run.md`, `refresh.md`, `lint.md`, `archive.md`, `review.md`, `remove.md`, `schema.md`, `search.md`, `bundle.md`, `queue.md`) all reference *"the `.config.yml` Guard defined in `SKILL.md`"* — they inherit this AskUserQuestion p …[+46 chars]
.claude/skills/bcos-wiki/SKILL.md: The human reviews diffs and runs `git commit` / `git push` when ready. · uses the network
.claude/skills/bcos-wiki/SKILL.md: This applies to `run`, `refresh`, and `create` (when source content is large).
.claude/skills/bcos-wiki/SKILL.md: Users who want a binary in collections-as-evidence must run `/collections add` explicitly.
.claude/skills/bcos-wiki/SKILL.md: ├── run.md ← /wiki run [<url>]
.claude/skills/bcos-wiki/SKILL.md: ├── ingest.md ← shared ingest pipeline (called by run/promote/create/refresh)
.claude/skills/clear-planner/SKILL.md: Step 2: Run Discovery
.claude/skills/clear-planner/SKILL.md: { "step": 2, "name": "Run Discovery", "status": "in_progress" }
.claude/skills/clear-planner/SKILL.md: **Run all three discovery scripts:**
.claude/skills/clear-planner/SKILL.md: bash .claude/agents/agent-discovery/find_agents.sh
.claude/skills/clear-planner/SKILL.md: bash .claude/skills/skill-discovery/find_skills.sh
.claude/skills/clear-planner/SKILL.md: python .claude/scripts/find_lessons.py --tags "#{scenarioType}"
.claude/skills/clear-planner/SKILL.md: Run discovery scripts (Step 2 results)
.claude/skills/clear-planner/SKILL.md: | | ------------------- | ------------------------------------ | --------------------------------------------------------- | ------------------- | | Integration Audit | Detect stale references in ecosystem | `python .claude/scripts/analyze_integration.py --staged` + AI review | **YES …[+455 chars]
.claude/skills/clear-planner/SKILL.md: | Scenario | Key Requirement | | ----------------- | ------------------------------------------------------------------ | | **AGENTING** | Check for ecosystem overlaps + run integration audit before commit | | **DOCUMENTAT …[+76 chars]
.claude/skills/context-audit/SKILL.md: Run all five audit categories against the scoped files.
.claude/skills/context-audit/SKILL.md: python .claude/scripts/build_document_index.py
.claude/skills/context-ingest/SKILL.md: | Input shape | Dispatch to | Why | |-------------|-------------|-----| | HTTP/HTTPS URL (article, GitHub, YouTube) | `/wiki run <url>` (the `bcos-wiki` skill, Path A) | Wiki owns external-source ingest, banner citations, schema validation, refresh tier | | Path inside `docs/_inbox/` a …[+508 chars]
.claude/skills/context-ingest/SKILL.md: If the input is mixed (e.g. Slack export *and* a URL), do mine first, then handle the URL via `/wiki run` separately, then return to ingest for whatever's left.
.claude/skills/context-ingest/SKILL.md: Run `python .claude/scripts/build_document_index.py` after material changes
.claude/skills/context-ingest/SKILL.md: **→ Rebuild Document Index** — Always: `python .claude/scripts/build_document_index.py`
.claude/skills/context-ingest/SKILL.md: **→ context-audit** — If a new data point was created: "Want me to run a quick CLEAR audit on the new doc?"
.claude/skills/context-mine/SKILL.md: Recommend: "Run context-ingest to classify and route these items"
.claude/skills/context-onboarding/SKILL.md: | What you see | What you do | |---|---| | User shares a URL, pitch deck, or describes their business | Gather from those sources, ask 2-3 follow-ups if needed | | Repo already has docs/, README, markdown files with business content | Scan the repo, map what exists | | User drops files …[+394 chars] · uses the network
.claude/skills/context-onboarding/SKILL.md: Before anything else, run **once** per onboarding session to make sure the BCOS-managed instructions are present in `CLAUDE.md`.
.claude/skills/context-onboarding/SKILL.md: This catches the `git clone`-without-`install.sh` case: if `CLAUDE.md` exists but lacks the `` / `` markers, the framework section is missing or unstructured. · uses the network
.claude/skills/context-onboarding/SKILL.md: If `.claude/bcos-claude-reference.md` doesn't exist yet (fresh clone), point `--source` at the upstream template available in this repo's tree (the same file install.sh would have copied).
.claude/skills/context-onboarding/SKILL.md: **First-run routing principle:** onboarding is allowed to identify all BCOS zones, but it should only create active data points after the user approves the architecture.
.claude/skills/context-onboarding/SKILL.md: | Material | First-run handling | |---|---| | Canonical facts, current decisions, project/task/business reality | Draft active data points in `docs/*.md` | | Raw notes, unsorted snippets, uncertain material | Keep in `docs/_inbox/` until triaged | | Future ideas, plans, or maybes | Par …[+578 chars]
.claude/skills/context-onboarding/SKILL.md: Options: **Activate** (set all to active, run index + wake-up) / **Adjust** (tell me what to fix)
.claude/skills/context-onboarding/SKILL.md: Run `python .claude/scripts/build_document_index.py` to generate the Document Index with DOMAIN one-liners
.claude/skills/context-onboarding/SKILL.md: Run `python .claude/scripts/generate_wakeup_context.py` to generate the Wake-Up Context for instant session orientation
.claude/skills/context-onboarding/SKILL.md: The checklist ships with install at `docs/.onboarding-checklist.md`.
.claude/skills/context-onboarding/SKILL.md: Ensure the `.claude/hook_state/` directory exists (it usually does from install.sh — check and create if missing).
.claude/skills/context-onboarding/SKILL.md: the dispatcher will create it on first run.
.claude/skills/context-onboarding/SKILL.md: **Run the catalog drift guard:**
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/validate_permissions_catalog.py
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/update.py
.claude/skills/context-onboarding/SKILL.md: Re-run the validator to confirm clean.
.claude/skills/context-onboarding/SKILL.md: If the answer is "Yes, multi-repo" (or the user confirms after explanation), run:
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/install_global_permissions.py
.claude/skills/context-onboarding/SKILL.md: Question: "When should the morning dispatcher run?"
.claude/skills/context-onboarding/SKILL.md: Run the schedule-dispatcher skill to execute today's scheduled CLEAR maintenance. It will:
.claude/skills/context-onboarding/SKILL.md: 3. Execute each job in sequence, appending one diary entry per job
.claude/skills/context-onboarding/SKILL.md: The portfolio aggregator picks it up on the next dispatcher run.
.claude/skills/context-onboarding/SKILL.md: The dispatcher will run in the wrong directory and writes meant for this repo's `docs/_inbox/` will be blocked.
.claude/skills/context-onboarding/SKILL.md: If "Recreate", call `mcp__scheduled-tasks__delete_event` (or the equivalent delete tool) on the bad task, then re-run Step 6d.
.claude/skills/context-onboarding/SKILL.md: That's intentional — fresh setups should over-monitor for the first 1-2 weeks until the auto-tuner suggests reductions after green-run streaks.
.claude/skills/context-onboarding/SKILL.md: Let the user invoke the first run on their terms.
.claude/skills/context-onboarding/SKILL.md: A fresh install has nothing to migrate and should never see the word.
.claude/skills/core-discipline/SKILL.md: **Significant change** (restructure a cluster, create new skills) → use clear-planner, run the full workflow
.claude/skills/core-discipline/SKILL.md: | Task Type | Action | | ------------------------- | ---------------------- | | Questions, commands | Respond directly | | Single-file fixes | Just do it | | Small changes (1-3 files) | Think briefly, execute |
.claude/skills/core-discipline/SKILL.md: A scheduled dispatcher run finishes clean green with zero findings (one-line summary keeps the dashboard "Ready" status meaningful)
.claude/skills/core-discipline/SKILL.md: **Special case — wrapping scripts with built-in prompts** (like `update.py`'s `[y/N]` prompt): invoke the script with `--dry-run` first, parse the output, surface the summary via `AskUserQuestion`, then re-invoke with `--yes` based on the user's choice.
.claude/skills/daydream/SKILL.md: If the file doesn't exist, this is the first run — use 2 weeks ago as the baseline.
.claude/skills/daydream/SKILL.md: # Read last run timestamp (or default to 2 weeks ago)
.claude/skills/daydream/SKILL.md: cat .claude/quality/last-daydream.txt 2>/dev/null || echo "no previous run"
.claude/skills/daydream/SKILL.md: git log --since="{last_daydream_date}" --name-only --pretty=format:"%h %s (%ar)" -- docs/ ':!docs/_bcos-framework/methodology/' ':!docs/_bcos-framework/guides/' ':!docs/_bcos-framework/templates/'
.claude/skills/daydream/SKILL.md: Report "No document changes since last run" and skip to Phase 3 (Imagine) for forward-looking reflection only.
.claude/skills/daydream/SKILL.md: git diff {last_daydream_commit}..HEAD -- docs/path/to/changed-file.md
.claude/skills/daydream/SKILL.md: python .claude/scripts/build_document_index.py --dry-run
.claude/skills/daydream/SKILL.md: python .claude/scripts/generate_wakeup_context.py
.claude/skills/daydream/SKILL.md: **Step 5b: Run maintenance scripts**
.claude/skills/daydream/SKILL.md: Daydream is the natural time to run periodic maintenance:
.claude/skills/daydream/SKILL.md: python .claude/scripts/prune_sessions.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/prune_diary.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/generate_wakeup_context.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/analyze_crossrefs.py
.claude/skills/daydream/SKILL.md: **Step 6: Record this run**
.claude/skills/daydream/SKILL.md: python .claude/scripts/record_daydream.py
.claude/skills/daydream/SKILL.md: **Document Index** — Run `python .claude/scripts/build_document_index.py` if files changed
.claude/skills/doc-lint/SKILL.md: If `.md`: Run markdown quality checks and cross-reference validation
.claude/skills/doc-lint/SKILL.md: If `.json`: Run JSON structure validation
.claude/skills/doc-lint/SKILL.md: Px_001: Run markdown quality check -> doc-lint (markdown category)
.claude/skills/doc-lint/SKILL.md: Px_002: Run example code validation -> doc-lint (cross_reference category)
.claude/skills/doc-lint/SKILL.md: Px_001: Run JSON structure validation -> doc-lint (json_structure category)
.claude/skills/doc-lint/SKILL.md: Px_002: Run markdown quality check -> doc-lint (markdown category)
.claude/skills/ecosystem-manager/SKILL.md: Run discovery to see what exists:
.claude/skills/ecosystem-manager/SKILL.md: bash .claude/agents/agent-discovery/find_agents.sh
.claude/skills/ecosystem-manager/SKILL.md: bash .claude/skills/skill-discovery/find_skills.sh
.claude/skills/ecosystem-manager/SKILL.md: Run it before committing.
.claude/skills/ecosystem-manager/SKILL.md: python .claude/scripts/analyze_integration.py --uncommitted
.claude/skills/ecosystem-manager/SKILL.md: Coverage gaps in install.sh, settings.json, state.json, .gitignore
.claude/skills/ecosystem-manager/SKILL.md: Add fix tasks to the plan and execute them before committing.
.claude/skills/ecosystem-manager/SKILL.md: [ ] **install.sh installs new files**
.claude/skills/ecosystem-manager/SKILL.md: Run after major development sessions or as part of monthly architecture review.
.claude/skills/ecosystem-manager/SKILL.md: Run `python .claude/scripts/wiki_schema.py list` to inspect page-types, lint-checks, and auto-fixes from `_wiki/.schema.yml` or the framework fallback.
.claude/skills/ecosystem-manager/SKILL.md: Run all 4 CI checks locally:
.claude/skills/ecosystem-manager/SKILL.md: python .github/scripts/validate_frontmatter.py # YAML metadata on all managed markdown
.claude/skills/ecosystem-manager/SKILL.md: python .github/scripts/validate_references.py # All registry paths resolve + state.json accuracy
.claude/skills/ecosystem-manager/SKILL.md: python .claude/scripts/analyze_integration.py --ci # Ecosystem wiring (install.sh, settings.json coverage)
.claude/skills/learning/SKILL.md: **Mechanism:** `python .claude/scripts/promote_resolutions.py` (the module's `__main__` calls `regenerate()`).
.claude/skills/learning/SKILL.md: Run the matching subcommand directly.
.claude/skills/lessons-consolidate/SKILL.md: python .claude/scripts/consolidate_lessons.py
.claude/skills/schedule-dispatcher/SKILL.md: Run `python .claude/scripts/update.py` first."
.claude/skills/schedule-dispatcher/SKILL.md: Report to the user: "schedule-config.json is malformed — fix before the dispatcher can run.
.claude/skills/schedule-dispatcher/SKILL.md: For each entry in `jobs`, decide if it should run today.
.claude/skills/schedule-dispatcher/SKILL.md: | `schedule` value | Runs when | |--------------------|----------------------------------------------------| | `"daily"` | Every day | | `"mon"`..`"sun"` | Only on that weekday …[+549 chars]
.claude/skills/schedule-dispatcher/SKILL.md: **For on-demand dispatch** (user said "run the audit-inbox job"): skip this step, run only the named job.
.claude/skills/schedule-dispatcher/SKILL.md: Build an ordered list of jobs to run.
.claude/skills/schedule-dispatcher/SKILL.md: python .claude/scripts/context_index.py --write
.claude/skills/schedule-dispatcher/SKILL.md: The cache TTL is 10 min (longer than a full dispatcher cycle), so all jobs in this run hit the same in-memory snapshot.
.claude/skills/schedule-dispatcher/SKILL.md: Last run timestamp per job?
.claude/skills/schedule-dispatcher/SKILL.md: Use the helper script — it creates `.claude/hook_state/` on first run and matches the allowlisted command prefix so it never prompts:
.claude/skills/schedule-dispatcher/SKILL.md: python .claude/scripts/append_diary.py '{"ts":"2026-04-15T09:04:12","job":"index-health","verdict":"green","findings_count":0,"auto_fixed":[],"actions_needed":[],"duration_s":4}'
.claude/skills/schedule-dispatcher/SKILL.md: **Fallback:** when `.bcos-umbrella.json` is absent (standalone BCOS install with no umbrella), preflight reduces to the `../` + absolute-path scans — no sibling-name list to check against.
.claude/skills/schedule-dispatcher/SKILL.md: After Step 4 completes (last job returned), verify that **every job listed in Step 2's run-list produced exactly one diary entry in this dispatcher tick**.
.claude/skills/schedule-dispatcher/SKILL.md: Read back the diary entries appended during this tick (use the dispatcher's in-memory record, or the tail of `.claude/hook_state/schedule-diary.jsonl` filtered to the current run's `ts` prefix if you're running on-demand).
.claude/skills/schedule-dispatcher/SKILL.md: **Added in schema 1.1.0.** Before applying auto-fixes (Step 5) or rendering the digest (Step 7), enrich each finding emitted in Step 4 with three computed fields and produce the run's headline string.
.claude/skills/schedule-dispatcher/SKILL.md: **Match against prior tick.** Scan diary entries from the **immediately-prior dispatcher tick** (the most-recent run before today, identified by the latest `ts` < today's run window).
.claude/skills/schedule-dispatcher/SKILL.md: | Run shape | Headline template | |---|---| | Green clean (0 findings, 0 framework) | "{Nth consecutive green run.}{recovery callout if any job verdict flipped error→green this tick.}" | | Green with frequency suggestions only | "All {N} jobs green.
.claude/skills/schedule-dispatcher/SKILL.md: And the run has a `headline` string ready for Step 7.
.claude/skills/schedule-dispatcher/SKILL.md: For each job run today, check recent diary:
.claude/skills/schedule-dispatcher/SKILL.md: **Last run was `error`** → suggest investigating, not frequency change
.claude/skills/schedule-dispatcher/SKILL.md: Both are overwritten each run.
.claude/skills/schedule-dispatcher/SKILL.md: Conditional sections render ONLY when their counts are non-zero — a green clean run is ~5 lines, an amber run with 5 findings is ~40 lines.
.claude/skills/schedule-dispatcher/SKILL.md: | 1 | `{emitted_by}` | `{primary_attr}` | {one-line meaning} | {`🔁 Nth run` if consecutive_runs ≥ 3, else blank} |
.claude/skills/schedule-dispatcher/SKILL.md: Run at {ISO timestamp} · `.claude/hook_state/schedule-diary.jsonl`
.claude/skills/schedule-dispatcher/SKILL.md: verdict emoji + finding count + inline status markers in Note column | | `💡 Suggestions` | `≥1` `frequency-suggestion` finding | Bullet list | | Footer | Always | Run timestamp, diary path, auto-commit status |
.claude/skills/schedule-dispatcher/SKILL.md: | Scenario | Verdict bar example | Top line | Action hint | |---|---|---|---| | Green clean | `**🟢 BCOS green** · 1 ran · 0 findings · 0 fixed · 4s` | `Headline string from Step 4c, e.g. "10th consecutive green run."` | `→ Nothing to act on.
.claude/skills/schedule-dispatcher/SKILL.md: Run `git rev-parse --abbrev-ref HEAD` to get the current branch.
.claude/skills/schedule-dispatcher/SKILL.md: This is the per-tick safety property: a stray hand-edit to a "generated" file on a day its owning job did not run still blocks auto-commit.
.claude/skills/schedule-dispatcher/SKILL.md: Globs are resolved against `git status --porcelain` paths (same surface the clean-tree rule already inspects).
.claude/skills/schedule-dispatcher/SKILL.md: **Emit the `job-missing-outputs-declaration` framework-finding only when** the job's run would have changed at least one path *outside* `GLOBAL_ALLOWED` (i.e. a path that *could* have been auto-committable had it been declared).
.claude/skills/schedule-dispatcher/SKILL.md: Run `git status --porcelain`.
.claude/skills/schedule-dispatcher/SKILL.md: `git commit -m "bcos: daily maintenance {YYYY-MM-DD}"` — no push, ever.
.claude/skills/schedule-dispatcher/SKILL.md: A BCOS install with no umbrella still writes the log — it just sits locally until somebody (or the dashboard) reads it.
.claude/skills/schedule-dispatcher/SKILL.md: The last thing the dispatcher does depends on whether the run produced anything that needs user judgement.
.claude/skills/schedule-dispatcher/SKILL.md: Otherwise — clean green run, zero findings, zero suggestions — output a short summary and stop.
.claude/skills/schedule-dispatcher/SKILL.md: **Why this rule:** if every run always asked a question, every scheduled run would show as "Awaiting input" in the dashboard even on clean days.
.claude/skills/schedule-dispatcher/SKILL.md: Or even shorter when the user is watching an on-demand run:
.claude/skills/schedule-dispatcher/SKILL.md: ("Do you want architecture review to run weekly?" is too abstract — `schedule-tune` handles that)
.claude/skills/schedule-dispatcher/SKILL.md: **Retry the failed job(s)** → re-run only the errored jobs (on-demand mode), then ask again with the new result
.claude/skills/schedule-dispatcher/SKILL.md: If the user says "run the {job-name} job now" or "run today's maintenance now":
.claude/skills/schedule-dispatcher/SKILL.md: Skip the schedule predicate — run only the named job(s)
.claude/skills/schedule-dispatcher/SKILL.md: ## On-demand run — {HH:MM} ({job-name})
.claude/skills/schedule-dispatcher/SKILL.md: If `daily-digest.md` does not yet exist (no scheduled run happened today), create it with a minimal header before appending the on-demand section.
.claude/skills/schedule-dispatcher/SKILL.md: DO append a diary entry per job with `"trigger":"on-demand"` so the run is tracked in history
.claude/skills/schedule-dispatcher/SKILL.md: Run another job
.claude/skills/schedule-dispatcher/SKILL.md: The morning scheduled run always OVERWRITES `daily-digest.md` fresh — so yesterday's on-demand sections are not preserved in the digest (diary retains them).
.claude/skills/schedule-dispatcher/SKILL.md: Every dispatcher run produces either a digest OR a user-facing error message.
.claude/skills/schedule-dispatcher/SKILL.md: `schedule-tune` — user-facing skill for changing config ("run audit twice a week")
.claude/skills/schedule-dispatcher/SKILL.md: If a run was wrong, add a corrective entry, don't mutate history.
.claude/skills/schedule-tune/SKILL.md: If you haven't set up BCOS scheduling yet, run `context-onboarding` Step 6.
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"run audit twice a week"*, *"change daydream to every 3 days"*, *"switch architecture review to quarterly"*, *"run index-health on weekdays only"*, *"audit on Tuesdays and Fridays"*
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"run the dispatcher at 08:30"*, *"move morning maintenance to 07:00"*
.claude/skills/schedule-tune/SKILL.md: Update the actual scheduled task's cron via `mcp__scheduled-tasks__update_scheduled_task` — that's what actually moves the run
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"what's my maintenance schedule?"*, *"when does audit run?"*, *"is architecture-review enabled?"*
.claude/skills/schedule-tune/SKILL.md: If the user proposes a cron that would run more than once per day, refuse: *"Dispatcher is designed to run once daily.
.claude/skills/schedule-tune/SKILL.md: | User says | Config edit | |----------------------------------------|----------------------------------------------------------------| | "run audit on Tuesday instead of Friday" | `jobs.audit-inbox.schedu …[+1012 chars]
.claude/skills/todo-utilities/SKILL.md: **Sequential Agent Invocation** — Tasks run one after another
CLAUDE.md: **Small changes (1-3 files)** — think briefly, execute.
CLAUDE.md: Auto-generated by `python .claude/scripts/generate_wakeup_context.py`.
CLAUDE.md: When unsure, run `context-ingest` and let it propose the route.
CLAUDE.md: **Post-work handoffs:** After integrating new content, offer to (a) rebuild the document index, (b) update related data points, (c) run an audit if architecture shifted.

Hooks (5)

.claude/settings.json (Stop): bash "$CLAUDE_PROJECT_DIR/.claude/hooks/auto_save_session.sh"
.claude/settings.json (PreCompact): bash "$CLAUDE_PROJECT_DIR/.claude/hooks/precompact_save.sh"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_commit_context_check.py"

Install scripts (1)

install.sh: sh install.sh

Medium risk: runs-instruction-instruction-network (.claude/agents/wiki-fetch/AGENT.md:93)
Medium risk: runs-instruction-instruction-network (.claude/skills/bcos-wiki/SKILL.md:150)
Medium risk: runs-instruction-instruction-network (.claude/skills/context-onboarding/SKILL.md:33)
Medium risk: runs-instruction-instruction-network (.claude/skills/context-onboarding/SKILL.md:50)
Low risk: scripts-present (.claude/agents/agent-discovery/find_agents.sh)
Low risk: scripts-present (.claude/bin/python3)
Low risk: scripts-present (.claude/hooks/auto_save_session.sh)
Low risk: scripts-present (.claude/hooks/post_commit_context_check.py)
Low risk: scripts-present (.claude/hooks/post_edit_frontmatter_check.py)
Low risk: scripts-present (.claude/hooks/precompact_save.sh)
Low risk: scripts-present (.claude/scripts/analyze_crossrefs.py)
Low risk: scripts-present (.claude/scripts/analyze_integration.py)
Low risk: scripts-present (.claude/scripts/append_diary.py)
Low risk: scripts-present (.claude/scripts/audit_node_configs.py)
Low risk: scripts-present (.claude/scripts/auto_fix_audit.py)
Low risk: scripts-present (.claude/scripts/bcos_inventory.py)
Low risk: scripts-present (.claude/scripts/build_document_index.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_archive.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_init.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_lint.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_queue_add.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_remove.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_review.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_search.py)
Low risk: scripts-present (.claude/scripts/consolidate_lessons.py)
Low risk: scripts-present (.claude/scripts/context_bundle.py)
Low risk: scripts-present (.claude/scripts/context_index.py)
Low risk: scripts-present (.claude/scripts/context_search.py)
Low risk: scripts-present (.claude/scripts/digest_sidecar.py)
Low risk: scripts-present (.claude/scripts/find_lessons.py)
Low risk: scripts-present (.claude/scripts/generate_wakeup_context.py)
Low risk: scripts-present (.claude/scripts/install_global_permissions.py)
Low risk: scripts-present (.claude/scripts/lifecycle_sweep.py)
Low risk: scripts-present (.claude/scripts/load_task_profiles.py)
Low risk: scripts-present (.claude/scripts/load_zone_registry.py)
Low risk: scripts-present (.claude/scripts/promote_resolutions.py)
Low risk: scripts-present (.claude/scripts/prune_diary.py)
Low risk: scripts-present (.claude/scripts/prune_sessions.py)
Low risk: scripts-present (.claude/scripts/record_daydream.py)
Low risk: scripts-present (.claude/scripts/record_resolution.py)
Low risk: scripts-present (.claude/scripts/refresh_ecosystem_state.py)
Low risk: scripts-present (.claude/scripts/refresh_wiki_index.py)
Low risk: scripts-present (.claude/scripts/run_wiki_canonical_drift.py)
Low risk: scripts-present (.claude/scripts/run_wiki_coverage_audit.py)
Low risk: scripts-present (.claude/scripts/run_wiki_graveyard.py)
Low risk: scripts-present (.claude/scripts/run_wiki_source_refresh.py)
Low risk: scripts-present (.claude/scripts/run_wiki_stale_propagation.py)
Low risk: scripts-present (.claude/scripts/scan_docs_structure.py)
Low risk: scripts-present (.claude/scripts/set_profile.sh)
Low risk: scripts-present (.claude/scripts/update.py)

Attribution and licence

First committed by

walm00

Publisher

Guntis Coders (Community)

Source

walm00/business-context-os · commit 4635683

Licence

MIT License (files served here)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-12

Contributors

walm00

AutoGineer is not affiliated with or endorsed by walm00.

Install from source

9 of its files are not served here, so there is no ZIP. walm00/business-context-os at 4635683

What it is

How it works

Requirements

Set it up

Usage

Documentation by walm00

Install

From zero to running

What it does

The wiki zone

The dashboard

Requirements

Updating

Maintenance

CLEAR — the methodology

What ships

Contributing

Origin

License

Collections Zone Architecture

Why a Collections Zone Exists

The Immutability Constraint — and Why It Forces a Pattern

Folder Layout

The _manifest.md Schema

Frontmatter (BCOS-aligned)

Body — the file table

Why markdown links instead of [[wikilinks]]

Sidecar .meta.md — When the Row Isn't Enough

Derived-Report Sidecar

Naming Convention — Soft, Scanned, Not Enforced

Soft-Delete Pattern

The collections-scan Job

Wake-Up Awareness

Quarterly Coverage Audit (daydream-adjacent)

Integration with context-ingest (Path 5 extension)

Integration with _wiki/

Future RAG / Vector / Knowledge-Graph Compatibility

Graph readiness

Retrieval readiness

Embedding-update logic

What's deliberately NOT pre-built

Schema and Governance

_collections/.schema.yml registry

Governance operations

Bootstrap behavior on bcos init in a new repo

Same pattern across BCOS

Distinctions — Quick Reference

Adoption Plan

See Also

Advantages

Limitations

Security

This brain runs

Attribution and licence

Install from source

The `_manifest.md` Schema

Why markdown links instead of `[[wikilinks]]`

Sidecar `.meta.md` — When the Row Isn't Enough

The `collections-scan` Job

Integration with `context-ingest` (Path 5 extension)

Integration with `_wiki/`

`_collections/.schema.yml` registry

Bootstrap behavior on `bcos init` in a new repo