agentleFS
waldo1001waldo1001/waldo.BCObservatory/AGENTS.md

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.

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
  1. Very specific:

    Start at llms.txt (root) or the section index content/<section>/llms.txt.

    line 8
  2. Very specific:

    Read docs/PLAN.md (architecture, decisions, milestones) and docs/DECISIONS.md before changing structure.

    line 45
  3. Distinctive:

    Every item is keyed by a stable id (videoId, Learn path, object key, post id).

    line 54
  4. Very specific:

    Commit messages: conventional prefixes (feat:, fix:, pipeline:, content:, infra:, docs:).

    line 68

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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

  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 not, and neither is a row with by: model. cautions on posts, videos and object pages are warnings scoped to the object and version they apply to.
  2. 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.state says what kind of text the page holds (D77): derived pages hold no model text: facts from the source (code, Learn, roadmap, sources.yaml) placed by deterministic code. unreviewed marks model text (summaries, narratives) Opus has not checked yet; reviewed text passed an Opus review against its source; flagged text failed one and is withheld or marked.
  3. Cite evidence, never memory: each page's evidence array 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 under data/code/ is the ground truth for those.
  4. Version applicability matters: object pages carry present_in, changed_in and versions (an object already in the oldest snapshot has introduced: null: it may be much older); timelines per type are in data/code/timelines/, version diffs in data/code/diffs/version/. A localization (BE, NL, ...) is an overlay on W1; see content/localizations/ and data/code/diffs/country/.
  5. 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.json also 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, and section, offset and limit read 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.md says 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) and docs/DECISIONS.md before 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.ts only, on the Claude subscription via claude -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) unless full_text: true with consent in sources.yaml. Raw community text and the LLM cache go to the private vault, never into this repo. npm run check:leak runs before every commit on the Mini.
  • Generated files live under content/ and data/; do not hand-edit them. Human corrections go in data/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 by schedule, workflow_dispatch or push to main only. Pull-request workflows run on ubuntu-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) has issue: <N> and status:, and builds one when the owner applies the spec-approved label to that issue; bcobs-spec writes every spec as status: draft and never approves one. A League build runs on branch league/<issue>-<topic> with a PR labelled league-building, commits there and never pushes. It never edits the spec it builds or CLAUDE.md (the League quarantines a build that does): the spec's ship-time edits wait in docs/built/<slug>.md until 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-build checks). To take over, follow CLAUDE.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 are content: nightly <date> (<n> items).

Layout

PathPurpose
sources.yamlsource 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/), D81

Download now (ZIP)

Does 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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.