Skip to content

Interfaces

The site for machines: its Majordomus layer with MCP resource URIs, how to connect an agent over MCP, and every published file described in OpenAPI.

.ai

The Majordomus layer of this repository

Every rule, decision, note and workflow the agents working here obey, as Majordomus indexes them. Each has an MCP resource URI and links to its source.

ai.json
adr6
ObjectMCP resourceSource
Personal hub on Zola with Flowbite Pro, deployed to GitHub Pages majordomus://adr/adr-0001 0001-personal-hub-on-zola-with-flowbite-pro-deployed-to-github-pa.md
Pages runs on a dedicated lundra runner when hosted runners are saturated majordomus://adr/adr-0002 0002-pages-runs-on-a-dedicated-lundra-runner-when-hosted-runners-.md
Every public repository, original work only, derived through gh and glab majordomus://adr/adr-0003 0003-every-public-repository-original-work-only-derived-through-g.md
Contact from the GitHub profile, CV facts from the owner, a derived GitHub profile majordomus://adr/adr-0004 0004-contact-from-the-github-profile-cv-facts-from-the-owner-a-de.md
Visuals are maximizable simulators on the best library, everything interlinked, enforced every task majordomus://adr/adr-0005 0005-visuals-are-maximizable-simulators-on-the-best-library-every.md
Experience on the landing page is mined from private sources into anonymised facts, guarded by an NDA gate majordomus://adr/adr-0006 0006-experience-on-the-landing-page-is-mined-from-private-sources.md
context21
ObjectMCP resourceSource
Repository AI context

The protocol of the layer: what it holds, who owns which half, how it is discovered, and what outranks what.

majordomus://context/ai.layer README.md
Tracked repository context

The tracked half of the layer and what each section under it is for.

majordomus://context/ai.repo README.md
Architecture decisions

Accepted, durable decisions about how this repository is built.

majordomus://context/ai.repo.adrs README.md
Applications

The contexts the tool suits, when each fits and when it does not, composed from use cases.

majordomus://context/ai.repo.applications README.md
CI model

The CI model Majordomus reads (gates.yaml) — which job of ci.yml runs which gate, and which changed paths select them; here every change runs every job.

majordomus://context/ai.repo.ci README.md
Deployments

One canonical object per deployment of this repository's service; every artifact built from it — the container image definition and its ignore file — is generated from it and none of them is authoritative.

majordomus://context/ai.repo.deployments README.md
Product features

What this repository's product does for a person, one feature per file, each made of things the other registries already own; every surface that presents a feature is derived from these files.

majordomus://context/ai.repo.features README.md
Knowledge

How repository knowledge is declared and discovered, never collected.

majordomus://context/ai.repo.knowledge README.md
Candidate records

What the tool derived from the ledger and git at an episode boundary and nobody has reviewed yet, discovered as a knowledge source class.

majordomus://context/ai.repo.knowledge.candidates README.md
Curated notes

What this repository chose to write about itself, discovered as a knowledge source class.

majordomus://context/ai.repo.knowledge.curated README.md
Mesh

One canonical object that says whether this repository's servers take part in the mesh, over which transports, and which machines' keys they trust; a machine whose key is not listed keeps it closed.

majordomus://context/ai.repo.mesh README.md
Profiles

How much context, effort and ceremony a task gets, declared per working mode.

majordomus://context/ai.repo.profiles README.md
Project model

Milestones as outcomes, issues as execution contracts, and a dependency graph that decides what is next.

majordomus://context/ai.repo.project README.md
Prompt assets

The provider-neutral prompts the tool renders, with the tokens it fills in.

majordomus://context/ai.repo.prompts README.md
Repository rules

The rule object format, where rules live, how they are loaded and composed.

majordomus://context/ai.repo.rules README.md
Project rules

The rules this repository writes for itself, resolved together with the vendored baseline.

majordomus://context/ai.repo.rules.project README.md
Session records

One immutable record per closed execution episode, derived from git and the ledger and shared with every surface.

majordomus://context/ai.repo.sessions README.md
Skills

Reusable provider-neutral operational procedures, loaded only when the task is about them.

majordomus://context/ai.repo.skills README.md
Use cases

The tasks people perform with the tool, each one a file with the commands, rules and claims it names and the scenario that proves it.

majordomus://context/ai.repo.use-cases README.md
Why this exists

The operational failure modes this repository's work is a response to, the audiences that recognise them and the areas they fall under, each one a file every projection is derived from.

majordomus://context/ai.repo.why README.md
Workflows

The multi-step processes a worker follows here, and when each applies.

majordomus://context/ai.repo.workflows README.md
document9
ObjectMCP resourceSource
Continuity majordomus://document/.ai/repo/workflows/continuity.md continuity.md
Every change: the owner's standing order, applied by every task majordomus://document/.ai/repo/workflows/every-change.md every-change.md
Taking work from the plan majordomus://document/.ai/repo/workflows/plan.md plan.md
The task lifecycle majordomus://document/.ai/repo/workflows/task-lifecycle.md task-lifecycle.md
Use cases majordomus://document/.ai/repo/workflows/use-cases.md use-cases.md
AGENTS.md majordomus://document/AGENTS.md AGENTS.md
CLAUDE.md majordomus://document/CLAUDE.md CLAUDE.md
GEMINI.md majordomus://document/GEMINI.md GEMINI.md
korczis.github.io majordomus://document/README.md README.md
knowledge8
ObjectMCP resourceSource
Nested Alpine components share property names: the inner one silently writes the outer one's state

When an Alpine component is placed inside another (the catalogue filter wraps the detail drawer).

majordomus://knowledge/alpine-scope-collisions alpine-scope-collisions.md
A public repository is the owner's work only when the owner wrote most of its commits, and its description does not say it is a copy

When scripts/fetch-index.mjs or the rule for listing repositories changes.

majordomus://knowledge/authorship-derivation authorship-derivation.md
glab 1.115 `auth token` prints its help text: store the GITLAB_TOKEN secret from the token itself

When setting or rotating the GITLAB_TOKEN Actions secret, or when a refresh reads GitLab anonymously or spends its GitLab budget.

majordomus://knowledge/gitlab-token-secret gitlab-token-secret.md
The owner's answers of 2026-11-15: the experience map, the derived categories, unable.cz never runs, and the scope of a full refresh

Before changing data/projects.toml category rules or its hidden list, the private engagement map, anything that would publish unable.cz, or the scope of what the hub reflects.

majordomus://knowledge/owner-decisions-2026-11-15 owner-decisions-2026-11-15.md
p5 2.x sets up asynchronously and then sets touch-action: none on every canvas of the page

When a p5 sketch is resized, recoloured or shares a page with other canvases.

majordomus://knowledge/p5-async-setup p5-async-setup.md
axe judges SVG text by its CSS colour and the box background, never by the fill it is drawn on

When a visual draws text into an SVG over shapes, gradients or a night-toned box.

majordomus://knowledge/svg-text-contrast svg-text-contrast.md
Zola 0.23 renders Tera 2: components, bracket indexing, and filters that bind tighter than ~

When a template under templates/ is written or changed.

majordomus://knowledge/tera2-templates tera2-templates.md
Chart and graph mount points take their size from width and height; grid items need min-w-0

When a visual (Cytoscape, ECharts, Chart.js, p5) is added or its card layout changes.

majordomus://knowledge/viz-mount-sizing viz-mount-sizing.md
mesh-declaration1
ObjectMCP resourceSource
mesh majordomus://mesh-declaration/mesh mesh.yaml
policy1
ObjectMCP resourceSource
.ai/repo/policy.yaml majordomus://policy/.ai/repo/policy.yaml policy.yaml
profile4
ObjectMCP resourceSource
debugging

reproduce, isolate, fix, and prove a defect fixed

majordomus://profile/debugging debugging.yaml
deep-work

design, architecture, cross-cutting change, or a problem with no known shape

majordomus://profile/deep-work deep-work.yaml
implementation

build a described feature or change within a known design

majordomus://profile/implementation implementation.yaml
routine

small, well-understood changes; rename, bump, wording, one-line fixes

majordomus://profile/routine routine.yaml
prompt4
ObjectMCP resourceSource
continue

resume a task from durable state instead of from someone's memory

majordomus://prompt/continue continue.md
debug

frame a defect so that the fix is proven, not asserted

majordomus://prompt/debug debug.md
handover

produce a continuation record body for the current task

majordomus://prompt/handover handover.md
review

review the working diff against the claimed scope and the finish contract

majordomus://prompt/review review.md
rule74
ObjectMCP resourceSource
Every user interface is built on Flowbite Pro

Every UI this repository builds or generates uses the owner's licensed Flowbite Pro shell, blocks and components on Tailwind.

majordomus://rule/fleet.ui-uses-flowbite-pro@1 ui-uses-flowbite-pro.v1.md
Architecture decision integrity

Every architecture decision the repository holds parses against the decision contract, claims an identity nothing else claims, and every relation and reference it makes resolves.

majordomus://rule/majordomus.adr-integrity@1 adr-integrity.v1.md
AI layer integrity

The repository's AI layer is real: the manifest declares a format this executable reads and every section it names exists, the checkout-local half is ignored by git and nothing under it is tracked, and no project data remains under the pre-.ai .majordomus/ path.

majordomus://rule/majordomus.ai-layout-integrity@1 ai-layout-integrity.v1.md
Blocker resolution

No task can be completed while any question on this branch is unresolved; it can still be finished as blocked, partial, no_match or failed.

majordomus://rule/majordomus.blocker-resolution@1 blocker-resolution.v1.md
Bootstrap integrity

The path from a human reader to the AI layer is unbroken — README.md names AGENTS.md, every generated instruction file points at .ai/README.md, and none of them carries a rule of its own.

majordomus://rule/majordomus.bootstrap-integrity@1 bootstrap-integrity.v1.md
Candidates are reviewed

A review queue that grows without bound is not reviewed. More candidates than the policy cap, a candidate that has waited longer than the policy age, or a candidate the tree does not track, is reported, not stopped; both numbers are declared once in the policy.

majordomus://rule/majordomus.candidates-reviewed@1 candidates-reviewed.v1.md
Catalogue integrity

Every use case and application describes the tool in terms the tool has — each command, doctrine and claim it names exists, and the two catalogues reference each other in both directions.

majordomus://rule/majordomus.catalogue-integrity@1 catalogue-integrity.v1.md
Checkpoint freshness

A task whose last checkpoint is older than its profile's interval is reported, not stopped.

majordomus://rule/majordomus.checkpoint-freshness@1 checkpoint-freshness.v1.md
Every public command is exercised and refuted

Every public command has a behavioural test and a negative test, computed from the registry and the coverage each case declares about itself rather than from a list someone maintains.

majordomus://rule/majordomus.command-coverage@1 command-coverage.v1.md
The command surface is declared and reconciled

Every command the binary dispatches is described by the shipped registry, every command the registry declares public is dispatched, and a command is public exactly when the usage text lists it.

majordomus://rule/majordomus.command-surface@1 command-surface.v1.md
Completion is gated

A task reaches the outcome completed only when no validation gate its own change set selects is known to be failing, and a gate's verdict discharges nothing once the files that select it have changed since the run.

majordomus://rule/majordomus.completion-gates@1 completion-gates.v1.md
Context budget

The always-loaded projection stays within its line budget, every reference in it resolves, it states no count that will go stale, and the assembled context fits the builder's own budget.

majordomus://rule/majordomus.context-budget@1 context-budget.v1.md
Context integrity

Every directory of the AI layer carries a context document, each one carries the contract, they compose into one deterministic chain for every path, and a tree that does not validate resolves nothing.

majordomus://rule/majordomus.context-integrity@1 context-integrity.v1.md
Dependency graph integrity

The issue dependency graph is acyclic, every edge names an issue that exists, and no issue is executing ahead of a dependency that is not done.

majordomus://rule/majordomus.dag-integrity@1 dag-integrity.v1.md
Decision records

Every entry in decisions.md carries the task, the head and the reason, so a decision can be found by the worker who needs it.

majordomus://rule/majordomus.decision-records@1 decision-records.v1.md
The decision threshold

A change that is hard to reverse records the decision behind it as a decision record, and names what it put in force; an ordinary change does not.

majordomus://rule/majordomus.decision-threshold@1 decision-threshold.v1.md
Define done before executing

The finish contract is evaluated line by line, and nothing else counts as done.

majordomus://rule/majordomus.define-done-first@1 principle-07-define-done-first.v1.md
A deployment is described once, and every artifact built from it is generated from it

A deployment of the executable is a canonical object of the layer against a closed contract; the container definition, its ignore file and the files of the provider it names are projections of it, never a second description.

majordomus://rule/majordomus.deployment-contract@2 deployment-contract.v2.md
Execution depth is not output verbosity

Think as hard as the task needs; report as briefly as the profile says.

majordomus://rule/majordomus.depth-is-not-verbosity@1 principle-06-depth-is-not-verbosity.v1.md
Doctrine wiring integrity

Every doctrine in this registry resolves to a validator that exists, is reached from every command it names, propagates failure, is proved by a test, and is run by CI — and every validator in the source is declared here.

majordomus://rule/majordomus.doctrine-wiring-integrity@1 doctrine-wiring-integrity.v1.md
Enforcement wiring

Every enforcement the policy declares is invoked by the hook it names, from a file the dispatcher will actually execute, without swallowing the exit code.

majordomus://rule/majordomus.enforcement-wiring@1 enforcement-wiring.v1.md
Externalise decisions and durable state

A decision you make goes into a record, dated, with what was rejected and why; a question for a person goes into the questions store.

majordomus://rule/majordomus.externalise-decisions@1 principle-03-externalise-decisions.v1.md
Handover integrity

The resolver runs and reports either the record for this worktree and branch or its clean absence; a malformed record is never silently skipped, and a record describing a history this checkout no longer has is reported.

majordomus://rule/majordomus.handover-integrity@1 handover-integrity.v1.md
Handovers transfer state, not transcripts

A handover says what is true now and the one next action; never conversation history.

majordomus://rule/majordomus.handovers-carry-state@1 principle-10-handovers-carry-state.v1.md
Parallel work requires isolation

Do not start a second task in a checkout that already has one; overlapping claims across worktrees are reported.

majordomus://rule/majordomus.isolated-parallelism@1 principle-09-isolated-parallelism.v1.md
Escalate capability and effort only when justified

The profile sets the default capability and effort; escalation is recorded, never assumed.

majordomus://rule/majordomus.justified-escalation@1 principle-05-justified-escalation.v1.md
Knowledge graph integrity

The graph the knowledge compiler builds from what the repository states has one node per identity, no edge with a missing end or without provenance, and no declared path or tracked source that no longer exists; a broken owned reference is a failure, a broken link an author wrote in prose is not.

majordomus://rule/majordomus.knowledge-graph@1 knowledge-graph.v1.md
Knowledge integrity

Every knowledge record is one evidenced, well-formed assertion. It is valid against its schema with no unknown key, its identity is unique and equals its file name, a verified record carries provenance, every reference it names resolves, a superseded record says what replaced it or why it was rejected, a candidate never claims to be verified, and no record carries a conversation.

majordomus://rule/majordomus.knowledge-integrity@1 knowledge-integrity.v1.md
Knowledge observation

While episodes keep closing, the knowledge they produced must keep being derived. A closed episode no derivation followed, once it is older than the freshness threshold, is a stopped writer; a lifecycle whose close path never calls the deriver while the policy switch is on is a writer that was never started.

majordomus://rule/majordomus.knowledge-observed@1 knowledge-observed.v1.md
Layout integrity

The directories the durable commands write into are installed rather than created on first use.

majordomus://rule/majordomus.layout-integrity@1 layout-integrity.v1.md
Ledger integrity

Every line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.

majordomus://rule/majordomus.ledger-integrity@1 ledger-integrity.v1.md
Lifecycle observation

A store that can be read is not a store that is being written. While episodes go on opening, the records a future worker resumes from must go on advancing, every lifecycle event received must leave evidence it arrived, and an episode that outlives the staleness threshold must be named rather than left open.

majordomus://rule/majordomus.lifecycle-observed@1 lifecycle-observed.v1.md
Load minimum sufficient context

The profile says what to load; discover everything that may apply and load only what does.

majordomus://rule/majordomus.minimum-sufficient-context@1 principle-02-minimum-sufficient-context.v1.md
Note integrity

Every outcome needs a note carrying the sections that outcome requires, and no transcript.

majordomus://rule/majordomus.note-integrity@1 note-integrity.v1.md
Obligation closure

A task that declares obligations reaches the outcome completed only when each one is established by the tool or has evidence, and that evidence still describes the tree or the commit it was taken over.

majordomus://rule/majordomus.obligation-closure@1 obligation-closure.v1.md
One worker, one clear scope

A task claims the paths it may touch, and touches only those.

majordomus://rule/majordomus.one-worker-one-scope@1 principle-04-one-worker-one-scope.v1.md
Policy completeness

Every policy value the code reads is declared in the skeleton policy, and no reader carries its own default for one.

majordomus://rule/majordomus.policy-completeness@1 policy-completeness.v1.md
Policy integrity

The policy and every profile parse, declare version 1, and carry no key the schema does not define.

majordomus://rule/majordomus.policy-integrity@1 policy-integrity.v1.md
Profile requirements

A profile may demand more than the shared contract — a regression test, a decision record — and finish refuses without it.

majordomus://rule/majordomus.profile-requirements@1 profile-requirements.v1.md
Project model integrity

Every milestone and issue file parses, carries the id its filename claims, and contains no key nobody reads.

majordomus://rule/majordomus.project-integrity@1 project-integrity.v1.md
Projection integrity

Every generated instruction file exists, matches the stamp it carries, and is never silently overwritten after a hand edit.

majordomus://rule/majordomus.projection-integrity@1 projection-integrity.v1.md
Prompt capture is proven, or reported unavailable

A repository that declares prompt capture has it wired below the model and proven by running it; the archive stays ignored and untracked, every prompt is present as both a record and a rendering, and neither carries anything the model said.

majordomus://rule/majordomus.prompt-capture@1 prompt-capture.v1.md
A prompt record carries its own identity, is bounded, and is private

Every captured prompt names the episode it belongs to or says why it cannot; the archive is readable by its owner alone, bounded by a declared retention policy, and never holds credential material verbatim.

majordomus://rule/majordomus.prompt-continuity@1 prompt-continuity.v1.md
Prompt integrity

Every repository-local prompt asset renders, and every token in it is one the renderer knows.

majordomus://rule/majordomus.prompt-integrity@1 prompt-integrity.v1.md
A session does not finish behind its own published site

A repository that publishes has a second tree — the one the public is being served — and no commit-level gate can measure it, because no change to any file can make it right or wrong. A session that lands work and leaves the publication owed has finished nothing the public can see, and every check stays green while that is true. The gates that measure a deployment are declared as such in the CI model, and finish asks them.

majordomus://rule/majordomus.publication-currency@1 publication-currency.v1.md
Questions store integrity

Every entry in open-questions.md parses, because a gate that cannot read an entry can be bypassed by mistyping one.

majordomus://rule/majordomus.questions-store-integrity@1 questions-store-integrity.v1.md
A record's changed_files names the work, not the tool's exhaust

The changed_files block of a checkpoint, a handover or a closed session names what the episode produced. Paths a declaration already calls generated, projected or local are classified out, and the classification reads those declarations rather than a list of its own.

majordomus://rule/majordomus.record-changed-files@1 record-changed-files.v1.md
Retention caps

The ledger, the handovers, the checkpoints and the session records stay under the caps the policy sets, so durable state does not grow without bound.

majordomus://rule/majordomus.retention-caps@1 retention-caps.v1.md
The roadmap is a projection, never a document

No document is a second authority for the roadmap, and no milestone types its own version. While a hand-written roadmap table exists, it can neither list a release no milestone was released in nor hide one that carried a milestone; a milestone's release (released_in) is inferred from the release records, never typed.

majordomus://rule/majordomus.roadmap-integrity@1 roadmap-integrity.v1.md
Rule package integrity

The repository's effective rule set is real: the vendored baseline matches its manifest file for file, every rule resolves with its dependencies and no two claim one identity, and no project rule reuses the vendored namespace.

majordomus://rule/majordomus.rule-package-integrity@1 rule-package-integrity.v1.md
Every object has a schema, and the rules resolve in one stated order

The order the rules apply in is written down rather than left in the code; every kind the tool reads declares a schema, every schema is named by a kind, and every path under the repository's AI layer is claimed by a source so that nothing is carried through unvalidated.

majordomus://rule/majordomus.schema-integrity@1 schema-integrity.v1.md
Scope integrity

A task touches only the paths it claimed; work found elsewhere is not accepted as done.

majordomus://rule/majordomus.scope-integrity@1 scope-integrity.v1.md
The episode boundary is drawn below the model, and its working context is local

Where a provider fires session events, the episode is opened and closed by that provider's hook rather than by the model, the start event hands the worker the bounded briefing the policy declares, and the working context each open freezes stays under the ignored half of the layer, carries the declared keys, and never carries a conversation.

majordomus://rule/majordomus.session-lifecycle@1 session-lifecycle.v1.md
Session records are shared objects with a closed field set

A closed execution episode is written once, into the layer's sessions section, against a schema that admits what the repository can prove and nothing else.

majordomus://rule/majordomus.session-records@1 session-records.v1.md
Sessions are workers, not memory

Durable state lives in records the repository keeps, never in a conversation.

majordomus://rule/majordomus.sessions-are-workers@1 principle-01-sessions-are-workers.v1.md
Skill integrity

Every skill the repository declares parses against the skill contract, names the directory it lives in, carries its sections, describes itself in terms no other skill uses, and every skill or example it refers to exists.

majordomus://rule/majordomus.skill-integrity@1 skill-integrity.v1.md
State consistency

The task record still describes this checkout — same branch, and HEAD at or ahead of the recorded commit.

majordomus://rule/majordomus.state-consistency@1 state-consistency.v1.md
Task continuity

A task finished as partial or blocked should leave a handover record, not only a note section.

majordomus://rule/majordomus.task-continuity@1 task-continuity.v1.md
A task on a repository whose mesh is enabled works on the mesh

When the repository declares its mesh enabled, an active task's scope is claimed on the mesh — `start` brings the checkout's shared server up and claims it, `check` and `finish` claim it again when a server answers — and a task completed without that claim is refused.

majordomus://rule/majordomus.task-on-the-mesh@1 task-on-the-mesh.v1.md
Use-case coverage

Every public command, and every guaranteed claim and MCP tool the policy asks for, is named and run by at least one active use case whose scenario executes against the real tool; a gap is a failure or a report according to the policy, never silence.

majordomus://rule/majordomus.use-case-coverage@1 use-case-coverage.v1.md
Verification integrity

Completion requires a verification command that actually ran and exited 0 over a tree that did not change under it; its exit code, duration and tree are recorded.

majordomus://rule/majordomus.verification-integrity@1 verification-integrity.v1.md
Verify outcomes, not activity

A test that ran and passed is evidence; a sentence saying it did is not.

majordomus://rule/majordomus.verify-outcomes@1 principle-08-verify-outcomes.v1.md
Every number on the site is measured, dated and derived

Figures come from data/github.json written by scripts/fetch-github.mjs and are shown with their date; the curated catalogue is data/projects.toml; llms.txt is derived and checked.

majordomus://rule/project.data-measured@1 data-measured.v1.md
Everything links to everything it names, through derived links that are proven

Every mark a visual draws, every term, language, technology, project, category and repository a page names leads to its page on this site (and to its source where there is none), in the page's language; links come from one derived index, never from addresses built by hand, and every link is resolved at build time and in the browser audit.

majordomus://rule/project.everything-interlinked@1 everything-interlinked.v1.md
Pages are front matter plus data; nothing is maintained by hand

Every page is described by front matter that matches static/schemas/front-matter.schema.json, everything else is derived from data that the scheduled refresh re-measures, and the whole site is published as data (site.json, llms.txt).

majordomus://rule/project.front-matter-contract@1 front-matter-contract.v1.md
Every text exists in every language, through Zola's multilingual features

Interface texts live in i18n/*.toml, grouped by feature, and reach templates through trans(); curated data carries a _cs twin for every text field; every page exists as x.md and x.cs.md; tags are Zola taxonomies; a gate fails on anything untranslated.

majordomus://rule/project.i18n-everywhere@1 i18n-everywhere.v1.md
No client, person or private source is ever named in this public repository

Work done under a non-disclosure agreement reaches the site only as anonymised, mined facts; no client or person name, private repository, path or copied text appears in any tracked file, built page or commit message, and the gate that checks it reads its list from outside the repository.

majordomus://rule/project.nda-never-named@1 nda-never-named.v1.md
Every page is also an educational, linked article, described in front matter

Every content page carries a Markdown article body and names the glossary terms it builds on (extra.terms); the glossary (data/glossary.toml) defines each term in both languages with a source; term pages and back-links are derived; a gate refuses a page without an article or terms, an unknown term, an unused term or an unchecked link.

majordomus://rule/project.pages-are-articles@1 pages-are-articles.v1.md
Search and social metadata are derived from front matter and data

Titles, descriptions, canonical URLs, Open Graph and Twitter tags, OG images and JSON-LD come from each page's front matter and data/, through templates/partials/seo.html and scripts/build-og.mjs, and are gated on the built site.

majordomus://rule/project.seo-derived@1 seo-derived.v1.md
The site is Zola, self-hosted, and deployed only by the Pages workflow

Zola 0.23 (Tera 2) builds the site from templates and data; every asset is self-hosted; master deploys through pages.yml after CI, and production is verified to serve the commit.

majordomus://rule/project.site-zola-pages@1 site-zola-pages.v1.md
A UI change passes the browser gate before it lands

Every page, at phone and desktop width in both themes, has no WCAG 2.2 AA violation, no console or network error, no horizontal overflow, CLS at most 0.1, every visual mounted, and every internal link resolving.

majordomus://rule/project.ui-quality-gate@1 ui-quality-gate.v1.md
Every page is built on Flowbite Pro

The site is the owner's licensed Flowbite Pro application shell and blocks on Tailwind 4 and the flowbite 4 plugin; no other kit, no Pro source file committed.

majordomus://rule/project.ui-uses-flowbite-pro@1 ui-uses-flowbite-pro.v1.md
Every visual goes through one component layer

p5.js, D3 and Apache ECharts are constructed only in static/js/viz/<name>.js, registered with KorczisHub.viz, lazy-loaded, themed from the CSS tokens and given a text alternative.

majordomus://rule/project.viz-component-layer@1 viz-component-layer.v1.md
Every visual is a maximizable simulator on the best library

Every visual that is not declared static can be maximized to the viewport, deep-linked, restored with Escape, and is a model the visitor drives through declared parameters whose state lives in the address; charts and graphs are Apache ECharts through the layer, D3 is for bespoke layouts and physics, p5 for generative art.

majordomus://rule/project.viz-ergonomics@1 viz-ergonomics.v1.md
scope1
ObjectMCP resourceSource
.ai/repo/scope.yaml majordomus://scope/.ai/repo/scope.yaml scope.yaml
skill1
ObjectMCP resourceSource
Build UI on Flowbite Pro

Build or change any user interface on the owner's licensed Flowbite Pro shell, blocks and components, and verify it before claiming compliance.

majordomus://skill/fleet-flowbite-pro SKILL.md
taxonomy8
ObjectMCP resourceSource
Getting started and adoption

Bringing the tool into a repository, new or old, without losing what people already wrote.

majordomus://taxonomy/adoption taxonomy.yaml
Completion and quality gates

Deciding whether work is finished, with a contract every line of which passes or fails.

majordomus://taxonomy/completion taxonomy.yaml
Sessions and handover

Stopping and resuming work across sessions and workers from durable state.

majordomus://taxonomy/continuity taxonomy.yaml
Drift and reconciliation

Detecting that policy, projections, state and git disagree, and putting them back in step.

majordomus://taxonomy/drift taxonomy.yaml
Extension

Adding a rule, a command or a use case as data, with the checks that follow from it.

majordomus://taxonomy/extension taxonomy.yaml
Repository knowledge

What the repository declares about itself, and the plan, searched and validated.

majordomus://taxonomy/knowledge taxonomy.yaml
Policy and enforcement

Declaring rules, proving they are wired, reproducing a finding.

majordomus://taxonomy/policy taxonomy.yaml
Parallel workers

Several agents or people on one repository: claimed scopes, overlap, who touched what.

majordomus://taxonomy/workers taxonomy.yaml

Indexed by Majordomus 1.0.1 from the tracked .ai/ tree; a gate refuses a change to .ai/ that was not indexed again. Source: majordomus run objects.list, capabilities.list.

MCP

Connect an agent over MCP

Majordomus serves this layer to any MCP client: the objects below as resources, its capabilities as tools. It runs in a checkout of the repository, over stdio or on loopback HTTP.

majordomus.dev
  1. 1

    Install Majordomus

    One binary for macOS and Linux.

    curl -fsSL https://majordomus.dev/install.sh | sh
  2. 2

    Clone the repository

    The layer is the repository's .ai/ directory; Majordomus reads it from the checkout.

    git clone https://github.com/korczis/korczis.github.io.git && cd korczis.github.io
  3. 3

    Add it to your MCP client (stdio)

    Run inside the checkout; the client starts the server when it needs it.

    claude mcp add majordomus -- majordomus mcp
  4. 4

    Or over HTTP, with Swagger

    The server prints its loopback address; the same capabilities answer at /mcp, /openapi.json and /swagger.

    majordomus serve ensure

OpenAPI

The site as an API

Every machine-readable file this static site publishes, described in OpenAPI 3.1. Read-only, no authentication; Swagger UI renders the description.

PathWhat it holds
GET/.well-known/api-catalog The API catalogue (RFC 9727): where the description, the documentation and the Majordomus layer are data
GET/ai.json The Majordomus layer of korczis/korczis.github.io: every object of .ai/ with its MCP resource URI data
GET/llms-full.txt Tomas Korcak: Software for evidence: AI agents that prove their work, honest instruments in the browser, knowledge you can check. text
GET/llms.txt Tomas Korcak: Software for evidence: AI agents that prove their work, honest instruments in the browser, knowledge you can check. text
GET/schemas/cv.schema.json Work history, education and spoken languages: facts no repository holds, written by the owner (ADR 0004). schemas
GET/schemas/experience.schema.json data/experience.json, written by scripts/mine-experience.mjs and checked by scripts/check-experience.mjs. Every engagement is under a legal NDA: it holds a neutral id, keys of the public vocabulary in data/experience-rules.toml, dates, rounded numbers and public technology names, nothing else. No name, path or free text. schemas
GET/schemas/front-matter.schema.json Every content/*.md carries this front matter (TOML). It drives the page's title, SEO, Open Graph and Twitter tags, OG image, JSON-LD and its place in the site; nothing about a page is typed in a template. Validated by scripts/check-front-matter.mjs. schemas
GET/site.json Software for evidence: AI agents that prove their work, honest instruments in the browser, knowledge you can check. data
GET/sitemap.xml Every page of the site, in both languages (sitemaps.org) data

Article

Why a personal site has interfaces

A page written for people is one way to read this site; the same facts are also published for programs. Nothing on this page is typed: each part is derived from a file the repository already holds, and a gate fails the build when the two drift apart.

The rules the AI agents working on this repository obey live in its .ai/ directory, supervised by Majordomus. The table at the top is Majordomus’s own index of that directory, so each object carries the address an agent asks for it by: its MCP resource URI. Any MCP client can read the same objects live from a checkout of the repository, together with the tools Majordomus provides.

The site itself is a set of files on GitHub Pages: the catalogue as site.json, the plain text for language models as llms.txt, the JSON Schemas its data is checked against. They are described in OpenAPI, so Swagger UI or any client generator can read them without guessing, alongside the JSON-LD every page carries.

Concepts on this page

The terms this page builds on, each defined in the glossary with a source to read further.

All terms
MajordomusTechnology
The owner's supervisory layer for AI-assisted work: one policy for every coding agent, scoped tasks, and finishes that must be proven.
MCPTechnology
The Model Context Protocol: an open protocol through which AI applications reach tools and data.
OpenAPITechnology
A standard, language-neutral description of an HTTP interface: its paths, operations and data, readable by people and tools such as Swagger UI.
AI agentConcept
A program that uses a language model to plan and act (edit code, run commands) toward a goal; Majordomus makes such agents prove their work.
JSON-LDConcept
Linked data in JSON embedded in a page, telling search engines and machines what the page is about (schema.org).
GitHub PagesTechnology
GitHub's hosting for static websites, deployed from a repository; this site and most project sites live there.