Knowledge
Concept
Coding agents are only as good as their context. Knowledge is how Greenlight gives every agent the customer-specific prose it needs — and lets agents help write that prose back.
Knowledge entries are Markdown documents stored in the Greenlight control plane, edited in the dashboard, and served to agents through MCP. They cover what’s in this Snowflake account, how this org uses its design system, the architecture of this app, the gotchas the team has discovered together.
Three scopes
Every entry is scoped to one of three subjects.
| Scope | What it covers | Who authors it |
|---|---|---|
| Org | Design-system usage notes, security and compliance policy summaries, naming conventions, internal infrastructure docs, “how we work” context. | IT |
| Integration | What lives in this Snowflake account, the warehouses an app may use, idiomatic SQL patterns, rate-limit guidance, post-mortems on common gotchas. | IT and app owners; agents propose entries |
| App | App-specific architecture notes, business-domain context, schema sketches, debugging recipes, owner notes. Seeded from greenlight.yml and the README on registration. | The app’s owner and any co-owners; agents propose updates |
Knowledge vs Skills
Skills bundled with the agent plugin are universal — identical for every customer, version-controlled in Greenlight’s monorepo, concerned only with the protocol. Knowledge is the opposite.
| Skills | Knowledge | |
|---|---|---|
| Where it lives | In the plugin package | In the control-plane database |
| Who authors it | Greenlight platform team | IT, app owners, and agents |
| How agents read it | Loaded at session start | MCP tool calls |
| How it gets updated | Plugin redistribution | Dashboard save or accepted agent proposal |
| Same for every customer? | Yes | No |
Authorship is iterative
A seeded app architecture entry starts as a verbatim copy of greenlight.yml. The agent appends a paragraph on schema decisions during the first build. IT rewrites the security paragraph during review. The citizen developer adds a Snowflake query that worked. The agent later proposes a correction when the schema changes.
No single fixed “source” can represent that lifecycle — so Knowledge doesn’t try. Every save is in the audit log with who, when, and the diff. The dashboard renders a per-entry history view from those events.
The proposal flow
Agents never write directly to knowledge_entries. They propose; humans review.
The agent calls greenlight.knowledge.propose with the new content and a rationale. The server records a pending proposal and surfaces it in the dashboard for review.
await greenlight.knowledge.propose({ scope: 'app', app_id: 'app_k9x2m3p', topic: 'architecture', title: 'App architecture', body_md: '...', rationale: 'Discovered a clean way to split the cron job from the API.', base_version: 3,});The reviewer sees the proposal in the dashboard with a diff against the live entry. They can:
- Accept as proposed — upserts the entry, increments version, emits two audit events.
- Accept with edits — same path, but the reviewer’s edits land and
last_editor_kindbecomeshuman. - Reject — the proposal is closed; the entry is untouched.
Stale proposals (where the entry has moved on since the agent read it) are marked superseded. The agent re-reads and re-proposes.
What agents read at runtime
Four MCP tools cover everything. Full specs in the MCP reference.
greenlight.knowledge.list— summaries, filtered by scope and parent.greenlight.knowledge.get— one entry’s body.greenlight.knowledge.search— full-text search over titles and bodies.greenlight.knowledge.propose— the agent write path.
Knowledge vs policy
Knowledge is advisory prose. getPolicies is the rules — structured rows that OPA evaluates at the pipeline gate. Two surfaces, two jobs: the pipeline blocks on policy rules; the agent reads Knowledge to understand how and why.