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.

Tip

Knowledge is co-authored. IT seeds an entry, the agent appends what it learns, the app owner edits for accuracy, and the next agent session reads everything they wrote.

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. Starts empty — IT and app owners write the first notes as the integration gets used.	IT and app owners; agents propose entries
App	App-specific architecture notes, business-domain context, schema sketches, debugging recipes, owner notes. Starts empty until useful context is authored.	The app’s owner and any co-owners; agents propose entries and updates

How an entry starts

Org Knowledge begins with a starter template. App and integration Knowledge start empty and fill in as your team learns facts worth carrying into future sessions.

• Org entries seed from a default template the first time the organization is set up — a design-system, a security-policy-summary, and coding-conventions starter. IT edits them to the house style.
• App entries start empty. The required docs block in greenlight.yml remains deployment documentation, separate from Knowledge. Owners create entries in the dashboard and agents propose them when useful context emerges.
• Integration entries start empty for every source — both the curated catalog services (GitHub, Slack, OpenAI, Salesforce, Snowflake, …) and custom build-your-own sources show an “Add the first entry” prompt in the dashboard until someone writes the first note. The agent already gets each integration’s live connection details (its base URL and how the credential reaches the app) when it lists the integrations it can use, so Knowledge is reserved for what your team learns about the source — schema, idiomatic queries, gotchas.

Seeded org entries carry a provenance marker, so the dashboard can show when an entry was seeded from the org template and later customized by a human. Authored app and integration entries live in the database and evolve through edits and proposals.

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

An owner creates an app architecture entry after the first meaningful design decision. The agent proposes a paragraph on schema decisions during the next 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.

Agent writes

The agent calls knowledgePropose with the new content and a rationale. The server records a pending proposal and surfaces it in the dashboard for review.

await knowledgePropose({
  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,
});

Human reviews

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_kind becomes human.
• 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.

• knowledgeList — summaries, filtered by scope and parent.
• knowledgeGet — one entry’s body.
• knowledgeSearch — full-text search over titles and bodies.
• knowledgePropose — the agent write path.

Note

Entries marked dashboard_only never appear in MCP responses, regardless of the agent’s bound user role. Knowledge meant for humans stays for humans.

Integration Knowledge also follows the integration’s availability. When IT makes an integration inactive, agents cannot list, fetch, search, or propose against its entries — even through an IT user’s agent — while the dashboard keeps the content available for maintenance. Reactivation makes the preserved entries visible again.

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.

Next

The agent protocol MCP, universal Skills, plugin packaging.

Source control & the policy gate Where Knowledge stops and policy starts.

MCP tools reference Every knowledge* call, input and output.

For IT Admins → Curate Knowledge Reviewing agent proposals and editing entries.