Skip to content

Canonical Knowledge Map

Where knowledge lives, and how to look it up.

This document defines the authoritative map of where documentation and procedural knowledge reside across the Bluefly estate.

CRITICAL RULE: Do not write documentation for procedures that should be represented as executable Gas City primitives (Formulas, Orders, Agent configs).

1. Where Does Knowledge Live?

Type of Knowledge Authoritative Location
Standards & Rules BluCity-Docs/Engineering-Standard/standards/ and rules/
Architecture Specs BluCity-Docs/Engineering-Standard/architecture/
Policies & Governance BluCity-Docs/Engineering-Standard/governance/
Drupal Reference BluCity-Docs/Engineering-Standard/reference/drupal/
Reusable Execution Methods (Runbooks) BluCity-Packs/*/formulas/*.toml (Gas City Formulas)
Scheduled / Event Triggers (Cron/CI) BluCity-Packs/*/orders/*.toml (Gas City Orders)
Agent Behavior & Configuration BluCity-Packs/*/agents/ (Agent configs)
Gas City Platform Platform Upstream Docs (https://docs.gascity.com/)
Work Execution History Gas City Beads (bd command) and Events

2. Lookup Order

When attempting to discover context or answer a question, follow this precise sequence to establish the highest authority first:

  1. BLU-BIBLE (BluCity-Docs/Engineering-Standard/indexes/BLU-BIBLE.md or equivalent index entry point)
  2. Engineering-Standard/ (Normative rules, standards, factory contracts)
  3. architecture/ (System design, spec boundaries)
  4. reference/ (Historical snapshots, external system notes)
  5. Upstream / External (Official documentation of the tool, e.g., docs.gascity.com)

3. Gas City Primitives vs Hand-Coded Documents

Bluefly embraces the Gas City model: Executable primitives replace static documentation.

If you are documenting a process, stop and determine if you are actually writing a Gas City primitive:

  • A Runbook or Standard Operating Procedure (SOP) ➔ Create a Formula (.toml in formulas/). Formulas encode the reusable HOW into verifiable, executable steps.
  • A Cron Job, Schedule, or CI trigger ➔ Create an Order (.toml in orders/). Orders decide WHEN to run Formulas.
  • A new role or workflow instruction for AI ➔ Create an Agent config (in agents/). Agent configuration establishes WHO performs the work and their operating parameters, not static text files.

4. "Before You Write a New Document" Checklist

Before creating a new Markdown file, run this checklist:

  • [ ] Search existing documentation: Does this belong in an existing Standard, Policy, or Architecture spec?
  • [ ] Check for a Formula: Are you writing a procedure? If so, encode it as a Formula in BluCity-Packs/. Do not create a static markdown runbook.
  • [ ] Check for an Order: Are you defining when something happens? If so, create an Order in BluCity-Packs/. Do not create a schedule table in markdown.
  • [ ] Check for an Agent Config: Are you defining AI behavior? Update the Agent configuration in BluCity-Packs/.
  • [ ] Create the Document: Only if the knowledge is purely structural, architectural, policy-driven, or catalog data, proceed to create a new Markdown document in the correct authoritative location.