Audiences, jobs-to-be-done and information requirements

This page is for anyone deciding what a page is for — its author, its reviewer, or whoever is designing the navigation it will sit in. It names the readers this product writes for, the job each of them arrives to finish, and the information a page must supply for that job to complete.

It exists because a surface can be accurate, well-owned and correctly bounded and still fail: the reader who needed it could not tell it was theirs, or reached it and found the one fact their decision turned on was somewhere else. Ownership answers who decides this fact. This page answers the different question of who needs it, to finish what.

It is an input to an information architecture, not a taxonomy for its own sake. Every audience below has at least one job, every job ends in a named decision or action, and every information requirement is traced to a surface that satisfies it today or recorded as a gap. The gaps are the operative output — they are the page-shapes that do not exist yet.

What governs this page

This page is downstream of five merged artifacts. It adds no claim to any of them and restates none of their definitions.

Ticket references are plain text, not links: the tracker is not publicly readable, so a link would only reach a login wall — and a link checker scores that wall as reachable, which makes the reference look verified when it is not.

What this page does not decide

• Which pages exist, and where they sit. AAASM-5594 designs the product-site and Docs Hub sitemaps from this model. This page supplies the requirements and the gaps; it does not draw the tree.
• Any product claim. Where an audience’s requirement names a product fact, the fact is cited to product-promise.md, risk-scenarios.md or a manifest row. Nothing here is a new capability statement, which is why this page carries describes_capability: false.
• Page metadata rules. page-standards.md owns the block, the field reference and the fifteen cross-field rules. This page consumes its audience key; it does not extend it.
• Ownership of any content type. That is content-ownership.md’s canonical-source table.

The reader axis, and why this page coins nothing

This is the part most likely to go wrong, so it is stated before the model rather than left implicit in it.

A reader vocabulary already exists, and this page does not own it. page-standards.md’s audience key takes one of six values — evaluator, developer, operator, security-engineer, contributor, auditor — and those six are the audiences below. Not analogues of them, not a refinement of them: the same six words, used for the same subject. Publishing a second reader vocabulary beside that key would create exactly the two-vocabularies defect this programme exists to eliminate, and it would do it on the one key an information architecture routes by.

The six are also already in content-ownership.md’s layer table, in its Primary audience column, which reads in full: anyone assessing the company at L0; evaluators, buyers, technical leaders at L1; teams, security engineers, operators at L2; application developers, operators, contributors, security researchers at L3; developers who want to see it run at L4; a visitor who landed on the repo at L5; contributors, auditors at L6. That column is the prose form of the same axis, and this page reconciles to it rather than beside it — its security researchers are security-engineer, and its buyers and technical leaders are evaluator.

Three of its entries are not reader classes, and none of the three maps to an audience value on its own:

• L0’s anyone assessing the company is an arrival, and it is outside what this product writes for entirely — the company site’s reader, not this product’s.
• L5’s a visitor who landed on the repo is also an arrival, but not out of scope: they become a contributor, a developer or an evaluator as soon as they have a job, which is what a README’s “where its documentation is” line exists to decide.
• L2’s teams is a collective, not a role — a team is some mixture of operator, security-engineer and developer, which is why the L2 cell names the first two alongside teams rather than instead of it. It routes to whichever member holds the job in hand, and no page targets it directly: audience is a list precisely so a page can name the two or three values a team comprises.

None of the three is a seventh audience.

The axis this sits on, and the one rule that binds it

ADR 0034 hand-off 7 fixes three vocabularies, each ranging over a different subject — an action takes an ADR 0033 §6 claim term, a documentation area takes a maturity label, a product in the portfolio takes a lifecycle value — and rules that no axis may be applied to another’s subject.

The reader axis sits outside all three. Hand-off 7 counts “three vocabularies in total”, and that count is ADR 0034’s to keep — this page is not adding a fourth row to someone else’s table, it is observing that the audience enum is a vocabulary hand-off 7 does not range over, and asking what follows. Its subject is a person arriving at a page, which is not an action, not a documentation area and not a portfolio product. Its vocabulary is the audience enum, its owner is page-standards.md, and hand-off 7’s rule applies to it in both directions:

• No term from another axis is written about a reader here. No audience below carries an availability value, a §6 claim term, a maturity label or a lifecycle value. A reader is not Unmeasured and an audience is not 🧪 Release candidate.
• No term is coined on the claim axis. Forbidden design 12’s coining clause is scoped to the claim axis alone; this page adds nothing to any axis, so the question does not arise. Every product fact cited below is quoted or linked from a page that already owns it.

The one thing this page does add is the job and the information requirement, and neither is a vocabulary. A job is a sentence about a reader’s intent; a requirement is a sentence about what a page must contain. Neither ranges over an action, an area, a product or a reader class, so neither collides with anything.

Crosswalk: seven role labels, six audience values

The parent scope names seven roles. They map onto six audience values, and the collapse is deliberate rather than a rounding error.

Two roles share evaluator, and the metadata key cannot tell them apart. An executive deciding whether to trial at all and an engineering leader deciding what to sequence want different pages, and audience: [evaluator] routes both to the same place. The distinction is real and it is carried by user_job, not by a seventh enum value — a page states which of the two it serves in the one field page-standards.md gives it — the one field that can express it, though that page reserves user_job for stating a page’s job generally, not for separating two audiences that share a value. Coining a seventh value would be an edit to someone else’s enum, made from a page that does not own it, to express something the existing schema already expresses.

That is a recorded limitation rather than a silent one: an automated router keyed on audience alone cannot separate EV1 from EV3. If a sitemap needs to, it reads user_job. Whether the enum should gain a value at schema_version: 2 is page-standards.md’s decision, and this page hands it the evidence rather than pre-empting it.

How to read an audience entry

Each of the six carries the same seven fields, and each field exists because a sitemap needs it.

Belongs elsewhere is an anti-persona in its operative form. Naming a person nobody is writing for is unfalsifiable; naming the content that must not be on a reader’s entry page is checkable against a candidate sitemap in a single pass. Where a role is genuinely out of scope for the whole product, it is recorded once at the end rather than repeated six times.

On the identifiers

Job ids are two letters and a digit (EV1, SE1, AU1, OP1, DV1, CO1); gaps are GAP-n. Neither shape is arbitrary. The capability manifest’s rows are a single letter and a digit, and the letter is its domain — S sdk, H host_action, N network, M mcp, L devtool_launch, C credentials, I identity, G degraded_mode, P platform, eighty rows in nine series. This page cites some of them by id, so a job called S1 and a manifest row called S1 would collide on exactly the identifier a checking reader follows. risk-scenarios.md lettered its scenarios F and T1–T3 for the same reason. Where a single-letter id appears below, it is the manifest’s and is named as such.

The letter is the domain, not the owning component, and G is where that distinction bites. Every G row is domain: degraded_mode — the series is about what happens when a control cannot run, not about the gateway. Only three of the eleven are owned by aa-gateway — G8, G9, G10; the other eight belong to aa-runtime (five), aa-proxy (two) and the SDK (one). This matters for reading the citations below rather than as a point of order: G9 is this page’s recurring failure-posture exemplar precisely because it is a degraded-mode row, and a reader who took G for “gateway” would look for degradation somewhere else and not find it.

evaluator

Who. Someone deciding whether this product should be adopted, and at what altitude they need the answer. Two roles: an executive or evaluator deciding whether to trial at all, and a PM or engineering leader deciding what to sequence and what to tell a stakeholder is not yet available.

Arrives knowing. The category, and a concrete worry — an agent did something, or plausibly could. Sometimes a competitor. Does not know the product’s mechanisms, its routing model, or its platform position, and should not need to.

Must be able to do. Reach an accurate account of what the product decides, on which paths, what is on by default and what it leaves uncovered, without opening an ADR; and separate what ships today from what is decided but not built.

Jobs.

Never hidden. The boundary clause, on the same screen as any headline that needs it (product-promise.md). The default posture — a capability that exists but is off is a different product from one that is on. The area’s maturity label. The channel and platform position. That an approval hold has no shipped operator surface today, which product-promise.md carries as Provisional.

Belongs elsewhere. Protocol semantics, policy field validation rules, ADR rationale, per-language API surfaces. An entry page that opens with an architecture diagram has moved L3 content onto an L1 route; per content-ownership.md, that is content at the wrong layer, not a more thorough page.

Entry · next · escalation. Entry: the product website (T6/L1), or this hub’s index — which carries two evaluator jobs in its Find what you need table but never names the role, gap GAP-1. Next: product-promise.md level 3 and source-of-truth.md. Escalation: ADR 0033 §5.3 for the platform matrix and §6 for the vocabulary, in the core docs.

security-engineer

Who. Security and risk reviewers, and the security researchers content-ownership.md names as an L3 audience. One value, because they read the same pages for the same reason: to find the edge of the boundary.

Arrives knowing. Threat modelling, and that vendor descriptions overstate. Arrives sceptical, which is the correct posture and should be rewarded rather than managed.

Must be able to do. Determine the trust boundary and its enumerated bypasses; find the failure posture of each control, including the ones that fail open; establish what an absent or degraded control reports; and file a vulnerability report at the right address.

Jobs.

Never hidden. The bypass catalogue. The failure posture of every control cited, including the silent fail-open on the budget store that risk-scenarios.md records as row G9. That the audit chain is tamper-evident rather than signed, and that emission is best-effort. The platform matrix, in both directions. Understating it is a defect too — ADR 0034 grades it below broadening “because it is less dangerous, not because it is acceptable”, and records that understatements in this programme were introduced while correcting overstatements, with at least one reaching main. A security reader is the audience an understated boundary misleads most.

Belongs elsewhere. Install ergonomics, SDK API surface, positioning. A security reader does not need a getting-started path on their entry page and will read one as evasion.

Entry · next · escalation. Entry: this hub’s security-model.md — which carries a superseded model today, recorded as gap GAP-5 below. Next: the core threat model and ADR 0033. Escalation: the capability manifest rows and the verification reports in the core repository.

auditor

Who. QA and assurance readers: anyone whose job is to check a published statement against something, rather than to build or to buy.

Arrives knowing. How to evaluate evidence. Does not know the codebase and should not have to read it to establish what backs a sentence.

Must be able to do. Take any published claim and reach the evidence it rests on, or establish that there is none and record that; and interpret a verification result for what it establishes rather than for what it suggests.

Jobs.

Never hidden. Which statements are Provisional, and why. The Tier 1 / Tier 2 publication gate in risk-scenarios.md. That a passing chain verification does not establish the log is whole. That absence of a finding is a fact about the observer.

Belongs elsewhere. Positioning and conversion copy. An auditor arriving at a marketing page has been misrouted, and no amount of accuracy in that page fixes it.

Entry · next · escalation. Entry: none on this hub today — the index does not mention this reader (gap GAP-1), and an entry alone would not be enough, because the evidence it would route to is not published either (gap GAP-4). Next: the determinations in risk-scenarios.md, which is the closest thing to a claim-to-evidence route currently published. Escalation: capability-manifest.yaml and the verification reports — both L6, and content-ownership.md states that nothing in L6 is a reader-facing page, which is the shape of the gap.

operator

Who. Platform engineers and SREs: the people who put the product in front of an agent and keep it there.

Arrives knowing. How to run a service. Does not know that routing is a thing they do per agent and per launch, which is the single most consequential thing this audience learns.

Must be able to do. Route an agent on one host; install the right artifact for their platform from a channel that carries it; observe what the stack recorded; and work out why a control did not fire.

Jobs.

Never hidden. That routing is per agent and per launch, so an agent nobody routed is outside everything. The per-channel and per-platform position — the manifest’s released_channels and released_platforms are per row, and risk-scenarios.md records that the proxy reaches macOS through crates.io only. Which controls are off until configured. The failure postures, so a silent fail-open is not discovered during an incident.

Belongs elsewhere. Production orchestration commitments. Helm, Terraform and Kubernetes are a research question under current project policy, not committed work, and open-core-boundary.md is where the self-host scope is stated. A page that reads as a production deployment guide has made a commitment the product has not.

Entry · next · escalation. Entry: this hub’s Getting Started section — whose two pages are both 🗺️ Planned, gap GAP-2. Next: docker-containers.md and self-host-observability.md, which describe shipping behaviour but are filed under Operations rather than on the entry route. Escalation: the core quick-start and CLI reference.

developer

Who. Application and AI developers integrating the product into an agent they are building.

Arrives knowing. Their framework and their language. Wants working code, and will judge the product on how quickly they get some.

Must be able to do. Add a policy checkpoint in their language; choose an SDK mode knowing what each one does; and find a runnable integration for the framework they are actually using.

Jobs.

Never hidden. That the SDK is advisory, and that a policy refusal blocks a wrapped tool only in the check-capable mode — product-promise.md’s default-posture table carries both. That an unadapted framework, or a call that does not go through the framework’s dispatch, is outside the wrapper: the manifest’s S11 and S10 carry exactly those two, and S12 the raw HTTP, subprocess and filesystem class — all three language: [python, node, go], which is what makes them the right citation for an audience that spans three languages. A quick-start that omits them has widened the claim by dropping a precondition. Per-language rows say more but say it narrowly: S1’s known_bypasses list the same items plus not calling init_assembly(), and S1 is Python — Go’s S8 has a different list.

Belongs elsewhere. The threat model, the deployment matrix, positioning. A developer needs the boundary, but as a precondition on their own code rather than as a security chapter.

Entry · next · escalation. Entry: README.md’s SDKs & components table, or documentation.md — both branch by language, and neither is in the sidebar (gap GAP-7). Next: the SDK documentation mounted at /python-sdk/, /node-sdk/ and /go-sdk/ by the aggregation pipeline, which is where the first checkpoint lives. Escalation: the core API reference and the runnable examples at L4.

contributor

Who. Maintainers and contributors, in any repository in the org, including the coding agents working under the org’s rules.

Arrives knowing. The repository they are in. Does not know the cross-repository truth hierarchy, and will otherwise fix a defect in the place they noticed it.

Must be able to do. Classify a fact and find its canonical owner; choose a sanctioned reuse pattern; write a page that satisfies the metadata contract; and route a correction to the source before the derivative.

Jobs.

Never hidden. That depth is not a defect — no rule in this programme may be cited to thin a component’s documentation. That understating is a defect too — graded below broadening by ADR 0034, but a defect, and a contributor trimming for brevity is the commonest way one gets introduced. That an ownership dispute is a decision, not an edit, and stops rather than resolves inside a content pull request.

Belongs elsewhere. Positioning copy and conversion paths. A contributor reading those is reading the wrong layer for their job.

Entry · next · escalation. Entry: page-standards.md. Next: content-ownership.md and claim-vocabulary.md. Escalation: ADR 0034 for precedence, waivers and the reviewer classes.

Roles this product does not write for

Recorded once rather than repeated as six anti-personas, because each is out of scope for every surface rather than for one route.

Information requirements

One row per (audience, job, requirement). What a page must supply is the contract: if a candidate page does not carry it, the job does not complete on that page. Where it is satisfied today is this model applied once to the surfaces that exist, which is what makes it a review instrument rather than a wish list.

Status values: ✅ satisfied — a published page carries it on that audience’s route; ◐ partial — a published page carries it, but not on that route, or not in full; ✗ gap — nothing published carries it.

Requirements for evaluator

Requirements for security-engineer

Requirements for auditor

Requirements for operator

Requirements for developer

Requirements for contributor

The gaps

This is the list AAASM-5594 turns into pages. Each row names the requirements it blocks and the page-shape it implies; none of them is a request to move an existing page without a job to justify it.

Two of these gaps are bounded by something that already exists, and the bound is the point. A gap that overstates an absence sends 5594 to build a page the hub already has — which is worse than missing the gap, because the duplicate then competes with the original for the same reader. Where a route exists and is merely thin, the row says so and narrows the ask to the residue.

The relation below is invertible, and that is a property worth relying on. Every requirement id in a Requirements it blocks cell names that gap back in its own Status cell, and no status cell names a gap that does not claim it — 24 pairs, checked mechanically in both directions. So “is every gap closed by this sitemap?” is a set comparison over the two tables, not a reading of them. It is deliberately not a separate machine-readable block: page-standards.md and AAASM-5601 own structured page data, a second block format invented here would be exactly the coin-a-vocabulary-someone-else-owns defect this page argues against, and 5601’s validator would not know to check it. Two Markdown tables that parse cleanly give 5594 the same guarantee without the new format.

Why GAP-7’s missing checkpoint is not a page this hub should write

IR-DV1-a asks for a language-specific first checkpoint reachable from this hub, and the temptation is to close it by writing one here. That would be the wrong fix twice over. content-ownership.md puts per-language API surfaces at L3 and forbids L2 a reference of its own for anything a component owns; and this repository’s own project instructions at .claude/CLAUDE.md say the hub orients readers toward component docs and does not re-author their install steps or API surface, “which would only drift”. A checkpoint written here would be a derivative reproducing its source at the same depth — the defect page-standards.md names when it forbids a summary that replaces its source.

So the closable half of GAP-7 is the route, not the content: the SDK mounts belong in the sidebar. The checkpoint itself is the SDK docs’ to carry, and if it is thin there, that is an L3 ticket against the SDK in question rather than anything 5594 can draw.

Four hand-offs, not gaps

Recorded here because they were found while deriving the gaps and would otherwise be lost, but none is this page’s to fix and none blocks a requirement.

• GHCR is a published channel that the manifest’s released_channels vocabulary does not contain. docker-containers.md states that five multi-arch images are published to ghcr.io/ai-agent-assembly; the manifest’s released_channels values across all eighty rows are crates_io, github_release, homebrew, install_script, pypi, npm and go_modules — eight distinct values counting the sentinel not_applicable, which is not a channel and must not become a column — with no Docker or GHCR value. GAP-3’s page-shape is a matrix generated from the manifest, so a matrix built faithfully from that vocabulary would ship without a GHCR column while the hub separately documents the images. Whether GHCR belongs in the manifest is the manifest’s owner’s call, not this page’s, and is now tracked as AAASM-5680 — but 5594 needs to know before it generates anything.

• glossary.md also carries the superseded model. product-promise.md names two pages still carrying the older framing — security-model.md and glossary.md. GAP-5 is scoped to the security entry page because that is the one on a security-engineer route, but a sitemap treating GAP-5 as the complete list of superseded surfaces will miss the glossary, which is owned separately by AAASM-5658.

• page-standards.md’s note that the capability manifest has not started is now stale. capability-manifest.yaml is present in the core repository under AAASM-5531 with a schema, a semantic validator and a CI gate. That affects the reserved status of capability_ids and the platforms[] hand-off, both of which that page marks as pending AAASM-5531. It is page-standards.md’s edit to make, at whatever schema version it decides.

• The evaluator value cannot separate EV1 from EV3. Recorded above; the evidence is handed to page-standards.md rather than resolved by coining a value here.

Using this model

To evaluate an existing page

Answer four questions in order. The first two are the ones that catch a misplaced page.

1. Which audience value, and which job? Name one of the six and one job id. A page that serves no job on this list either has an unnamed audience — in which case name it — or does not need to exist. This is the same question page-standards.md’s audience and user_job keys ask, so a conforming page has already answered it.
2. Does it carry every requirement for that job? Walk the rows for that job id. A missing requirement is either a defect in the page or a link the page must add.
3. Does it carry anything from belongs elsewhere? Content for another audience on this reader’s route is the commonest cause of a page that is accurate and still unusable.
4. Is anything from never hidden absent? That list has no exceptions, and its items are the ones a redesign removes first because they are the least attractive.

To evaluate a proposed navigation

1. Every audience has an entry. Six values, six routes. A value with no entry means a reader with no way in.
2. Every route reaches its escalation in three steps. Entry, next, escalation. A fourth step is a route nobody finishes.
3. No route opens on a 🗺️ Planned page. Gap GAP-2 is what that looks like when it happens.
4. Every gap above is either closed by a page in the proposal, or is carried forward as a named open item. A sitemap that silently drops one has not resolved it.
5. No route requires a reader to reach L6 to finish their job. Where it does today, that is gap GAP-4 and the fix is a surface, not a deep link.

How this page meets its acceptance criteria

What this page hands off

Last reviewed: 2026-08-07 — AI Agent Assembly Team

Last updated: 2026-08-07 by AI Agent Assembly Team