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.

Brand assets, not just prose

An entry can carry attached image files alongside its Markdown — your logo, icon mark, wordmark, favicon, an app’s architecture diagram.

This exists because of a specific failure. If your design system is a document that says “the logo goes top-left,” an agent asked to build a header has no logo, so it draws one. The result looks plausible, is not your company’s mark, and ships. Attach the real files to your design-system entry and the agent uses those instead.

Each asset carries a role (logo-primary, logo-mark, logo-wordmark, icon, favicon, illustration, diagram) and a theme (any, light, dark), so “use the company logo, the version that works on a dark header” is an exact lookup rather than a guess at a filename. A required description doubles as alt text and as the agent’s hint for when to reach for that particular file. Reference an asset from the entry body with ![Primary logo](gl-asset:logo-primary).

Agents read assets; they never upload them. Brand approval is a human act, and it happens in the dashboard.

Note

Agents copy assets into your app’s repository — public/logo.svg, and .greenlight/icon.svg for a branded dashboard tile. The deployed app serves its own files, so it keeps working whatever happens to the control plane, and the asset is reviewed and scanned like any other committed file. The trade-off: after you replace a logo in Greenlight, an app keeps serving the copy already committed to its repo — a rebuild rebuilds that file. It takes the new mark when someone asks its agent to update it.

Uploads are limited to SVG, PNG, JPEG, and WebP at up to 2 MB each. SVGs containing scripts or remote references are refused — export a static file and it will pass.

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

Six MCP tools cover everything. Full specs in the MCP reference.

• knowledgeList — summaries, filtered by scope and parent.
• knowledgeGet — one entry’s body, plus the metadata for any assets attached to it.
• knowledgeSearch — full-text search over titles and bodies.
• knowledgeAssetList — attached images, filterable by role. Agents are instructed to call this before putting the organization’s mark anywhere in an app, and to omit the mark rather than draw one when nothing is attached.
• knowledgeAssetGet — one asset’s metadata and a short-lived download link.
• knowledgePropose — the agent write path, for prose only.

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.

The same holds for attached assets: an asset is exactly as visible as the entry it belongs to. Assets on a dashboard_only entry never reach an agent.

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 protocolMCP, universal Skills, plugin packaging.

Source control & the policy gateWhere Knowledge stops and policy starts.

MCP tools referenceEvery knowledge* call, input and output.

For IT Admins → Curate KnowledgeReviewing agent proposals and editing entries.