waldo.BCObservatory
AGENTS.md13 starsChanged 24 days agoMITView on GitHub
BC Observatory weaves official and community knowledge about Microsoft Dynamics 365 Business Central (BC) into one cross-referenced, agent-first knowledge base. This file is the entry point for humans and agents alike. 1. Start at llms.txt (root) or the section index content/<section>/llms.txt. Every page under content/ is markdown with strict frontmatter (schemas/frontmatter.*.json): id, type, tier, summary, evidence, links. links.related (D106) holds labelled cross-links: fixes, documents and names are stated by a source or a person; possibly related and relation unknown are…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository5 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- bcobs-specSkill
- sdd-buildSkill
- sdd-draftSkill
- sdd-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Start at llms.txt (root) or the section index content/<section>/llms.txt.
- Very specific: line 45
Read docs/PLAN.md (architecture, decisions, milestones) and docs/DECISIONS.md before changing structure.
- Distinctive: line 54
Every item is keyed by a stable id (videoId, Learn path, object key, post id).
- Very specific: line 68
Commit messages: conventional prefixes (feat:, fix:, pipeline:, content:, infra:, docs:).
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md - how to work in and with BC Observatory
BC Observatory weaves official and community knowledge about Microsoft Dynamics 365 Business Central (BC) into one cross-referenced, agent-first knowledge base. This file is the entry point for humans and agents alike.
If you are an agent answering questions with this repository
- Start at
llms.txt(root) or the section indexcontent/<section>/llms.txt. Every page undercontent/is markdown with strict frontmatter (schemas/frontmatter.*.json):id,type,tier,summary,evidence,links.links.related(D106) holds labelled cross-links:fixes,documentsandnamesare stated by a source or a person;possibly relatedandrelation unknownare not, and neither is a row withby: model.cautionson posts, videos and object pages are warnings scoped to the object and version they apply to. - Trust tiers:
official= Microsoft (Learn, BCApps, BCQuality, Microsoft's channel, the AL Language extension's marketplace changelog);community= everyone else;mixed= hub pages that merge both. Say which tier a claim comes from.review.statesays what kind of text the page holds (D77):derivedpages hold no model text: facts from the source (code, Learn, roadmap, sources.yaml) placed by deterministic code.unreviewedmarks model text (summaries, narratives) Opus has not checked yet;reviewedtext passed an Opus review against its source;flaggedtext failed one and is withheld or marked. - Cite evidence, never memory: each page's
evidencearray carries the source URL, date, commit SHA or video second. Quote at most what the page quotes. Never invent object IDs, field numbers or version numbers; the code pillar underdata/code/is the ground truth for those. - Version applicability matters: object pages carry
present_in,changed_inandversions(an object already in the oldest snapshot hasintroduced: null: it may be much older); timelines per type are indata/code/timelines/, version diffs indata/code/diffs/version/. A localization (BE, NL, ...) is an overlay on W1; seecontent/localizations/anddata/code/diffs/country/. - Sections:
topics/(Learn hubs),objects/<type>/<id>(AL objects of W1 and Microsoft's first-party apps, BC28-30),localizations/,features/(Microsoft 365 roadmap),videos/,posts/(community, derived),sources/(footprints),digests/(weekly, with the deprecation radar),changes/<repo>/<n>(merged pull requests of Microsoft's Business Central repositories, BCApps ones joined to the object pages they changed, D61),releases/al-<version>(the AL Language extension's changelog, one page per version, D85),hotfixes/<update>(Microsoft Support hotfix lists, one page per update, each entry anchored by its ID, D106),guidelines/<repo path>(BCQuality rules and review skills, one page per file, the rule's own text under MIT, D126). Lookups:data/index/pages-*.json+index-manifest.json(every page's metadata),data/index/docs-objects.json(Learn page <-> object by exact id),data/code/drift.json,data/graph/(the galaxy;landed.jsonalso lists the week's code changes, D80). The MCP server (packages/mcp,npx bc-observatory) serves exactly these as bc_ tools (D108): bc_search, bc_brief, bc_ls, bc_cat, bc_get_object, bc_diff_object, bc_localization, bc_whats_new, bc_blog_footprint, bc_feedback, plus bc_status for health; brief answers in five layers (Learn with key facts, code, what changed, heads up, gaps), search groups its hits by layer (D106); search covers fields, events and procedures (data/index/symbols-*.json, D86) and ranks like the site's own search; sort: 'date' lists the matches newest first (D101); a page over 30,000 characters comes back compact, andsection,offsetandlimitread one section (D93). Procedure bodies are not here by policy; object pages list calls and callers per object (data/code/graph/<major>/, D67); the plugin also connects bc-code-atlas (Stefan Maron) for bodies and per-procedure edges and Microsoft's Learn MCP for reading Learn pages (D96;plugin/README.mdsays what it installs), and every object page says how to ask it (D75).
If you are an agent (or human) changing this repository
- Read
docs/PLAN.md(architecture, decisions, milestones) anddocs/DECISIONS.mdbefore changing structure. - The pipeline is deterministic first, LLM last, only on deltas. Facts come from validators, not from prompts.
- LLM calls go through
pipeline/lib/llm.tsonly, on the Claude subscription viaclaude -p. No Anthropic API key, ever. Never pass--bare. Roles:facts= Haiku,prose= Sonnet,review= Opus (config/models.json). - Content policy (
CONTENT-NOTICE.md): Microsoft full text; community sources derived only (summary, quotes under 25 words, links) unlessfull_text: truewith consent insources.yaml. Raw community text and the LLM cache go to the private vault, never into this repo.npm run check:leakruns before every commit on the Mini. - Generated files live under
content/anddata/; do not hand-edit them. Human corrections go indata/overrides/*.yaml, which the pipeline merges last. - Every item is keyed by a stable id (videoId, Learn path, object key, post id). No title matching outside the one-off seed import.
- Secrets exist only in the Mac Mini's
/Users/bcobs/.config/bcobservatory/env. The repository has no secrets. - Workflows that run on the self-hosted runner (
runs-on: [self-hosted, bcobs]) are triggered byschedule,workflow_dispatchorpushtomainonly. Pull-request workflows run onubuntu-latest. - A spec under
docs/specs/may be built by waldo.Jarvis's League instead of by hand. The League reads only specs whose frontmatter (---on line 1) hasissue: <N>andstatus:, and builds one when the owner applies thespec-approvedlabel to that issue;bcobs-specwrites every spec asstatus: draftand never approves one. A League build runs on branchleague/<issue>-<topic>with a PR labelledleague-building, commits there and never pushes. It never edits the spec it builds orCLAUDE.md(the League quarantines a build that does): the spec's ship-time edits wait indocs/built/<slug>.mduntil the PR's review moves them into the spec. Do not build such a spec by hand while that branch or PR exists, and do not approve one while you are building it (/sdd-buildchecks). To take over, followCLAUDE.md"Taking over from the League". Skills:bcobs-spec(write),sdd-draft(issue to draft),sdd-build(build, both modes),sdd-review(review a League or build PR, and apply a League build's spec edits). - Commit messages: conventional prefixes (
feat:,fix:,pipeline:,content:,infra:,docs:). Nightly commits arecontent: nightly <date> (<n> items).
Layout
| Path | Purpose |
sources.yaml | source registry, community-editable by PR (schemas/sources.json) |
config/ | taxonomy (galaxy systems), versions, countries, models, budget, tooling pins |
schemas/ | JSON Schemas for frontmatter, sources, manifest items, graph, AL objects, diffs, LLM outputs |
pipeline/ | the nightly pipeline: lib, orchestrator, ingest, caption, extract, code, summarize, link, validate, review, render |
content/ | generated knowledge base (markdown + frontmatter) |
data/ | generated machine data: manifest, captions (Microsoft only), code JSON, indexes, graph, roadmap, overrides |
site/ | Astro site, deployed to GitHub Pages; site/src/about/about.md is the owner's hand-written About text (D83), the one prose file that is not generated: edit it directly |
packages/mcp/ | the bc-observatory MCP server (npx) |
plugin/ | Claude Code plugin (skills + MCP config) |
infra/mini/ | Mac Mini provisioning and nightly runner scripts |
docs/ | PLAN, DECISIONS, RUNBOOK, CONTENT-NOTICE, design brief and design handoff; docs/specs/ holds feature specs |
tests/ | schema, unit and golden tests with fixtures |
Running things
npm ci
npm run validate:sources # schema + policy check of sources.yaml
npm run typecheck && npm test # no network, no LLM
npm run validate:content # frontmatter schemas, ids, cross-references, relative links in content/
npm run check:leak # community text never in the public tree (shingle scan when the vault is present)
npm run llm:ping # one uncached claude -p call: proves subscription auth + model family
npm run ingest # discovery only (git, RSS, APIs), writes data/manifest
npm run nightly -- --dry-run # full orchestrator with LLM_CACHE_ONLY=1
npm run nightly -- --stages derive # re-render derived data only (writes content/ and data/), D81Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

