Documentation Gaps and Contradictions After beta.55–beta.96

[Aries]

Hi Anna team,

I reviewed the Anna developer documentation against changelog posts #81, #88, #100, #106, and #176. I also checked llms.txt and llms-full.txt against the documentation corpus.

This post includes only issues that may require action. Correctly documented features and internal changes without developer-facing impact have been excluded.

The review is based on the documentation snapshot from August 4, 2026 at staging.anna.partners. Some issues may have been fixed since then.

Summary

Across 78 changelog items and 84 documentation pages, I found:

Category	Count
Outdated documentation	7
Missing documentation	9
Partially updated documentation	24
Internal contradictions	19
Confirmed llms.txt / llms-full.txt issues	4

The most urgent problems are outdated statements because developers may follow instructions that are now incorrect.

The seven outdated changelog findings consolidate into six defects below because changelogs #100 and #106 both expose the same stale “globally unique” slug statement.

---

P0 — Outdated Documentation

1. Slugs are still described as globally unique

Changelog #100 says new apps publish as @handle/slug, and a slug only needs to be unique within the developer’s namespace.

Changelog #106 says the old global UNIQUE(slug) constraint was replaced by UNIQUE(developer_id, slug).

However, app-listing still describes slugs as globally unique, while host-api-files says they are unique per developer namespace and that bare slugs are rejected.

Suggested fix: replace globally unique with the per-developer uniqueness rule and show the canonical @handle/slug form.

2. Slugs are described as immutable immediately after creation

Changelog #100 says a slug can be renamed before publication or installation and becomes frozen afterward with SLUG_FROZEN.

The CLI reference documents apps rename-slug, but app-listing says a slug “can never be changed” and that the Console disables it immediately after creation.

Suggested fix: document the actual lifecycle—editable before publication or installation, frozen afterward—and explain SLUG_FROZEN.

3. Bundle asset URLs use the pre-namespace format

Changelog #100 says assets are served from:

/{handle}/{slug}/{version}/{path}

It also says handle changes receive transparent 301 redirects.

The documentation still shows:

GET /anna-apps/{slug}/{version}/{relative_path}

The slug-only form appears on app-ui-bundle, app-ui-overview, app-ui-windows, app-quickstart, and local-dev. The handle-bearing format and 301 behavior are not documented.

Once two developers can use the same slug, a slug-only URL is no longer unambiguous.

4. Bundle and binary size limits are stale

Changelog #176 raises the limits to:

• 1 GB total per app bundle

• 100 MB per bundle file

• 1 GB per platform for binary assets

app-ui-bundle still lists 50 MB as the total bundle limit and presents it as enforced at bundle/init.

The new limits could not be found in the reviewed documentation.

5. The documented version-bump behavior is reversed

Changelog #176 says the server never invents versions. Publishing changed content with a frozen version should return a 400 and require an executa.json bump.

executa-publish instead says:

The version number auto-bumps SemVer patch unless you set a specific value in the manifest first.

These statements describe opposite behaviors.

6. The version-pin matrix is stale

Changelog #176 gives the following matrix:

dispatcher_version          0.16.0
anna-app-schema             0.16.0
anna-app-core               0.14.0
@anna-ai/app-runtime        0.13.0
anna-app-runtime-local      0.2.0a15
@anna-ai/cli                0.1.38

host-api-vs-executa still says dispatcher_version=0.10.0, while the other concrete package versions are missing.

Suggested fix: maintain one authoritative compatibility matrix and update it as part of every release.

---

P1 — Missing Documentation

#	Missing behavior	Suggested location
1	The local dev harness forwards systemPrompt or system_prompt during agent.session.create.	local-dev-llm or the local harness section of host-api-agent
2	Real bridge mode forwards negotiated response_format to the platform completion endpoint.	CLI real-mode documentation
3	Qwen3.7 model catalog, live per-plan model counts, and family-grouped settings.	host-api-llm or a model-availability page
4	Equal-partner provider presentation and removal of the regional provider popup.	Model/provider documentation
5	chrome: "vibrancy" and transparent: true in UiViewSpec.	ui-manifest
6	GET /anna-apps/{id}/permissions, including computed missing grants.	App endpoint reference or permissions guide
7	On-demand waking and the transient, retriable agent_waking error.	host-api-tools and the protocol error reference
8	Per-tool and reconciliation-triggered deployment progress.	host-api-tools
9	Dev registration automatically grants llm + image + upload, and the local harness routes Executa host/uploadFile.	Local-development guide

The first two are environment-specific behaviors. Documenting the parameter in the production API does not tell developers whether the local or real bridge forwards it.

---

P2 — Partially Updated Documentation

#	Feature	Missing or unclear documentation
1	CLI 0.1.27 upgrade	Concrete minimum/current CLI version
2	agent.session.refresh	Optional ttl_seconds; existing pages show incompatible parameter sets
3	Browser SDK 0.8.0	Package-version matrix and the 0.7.0 → 0.8.0 boundary
4	Pinned runtime 0.2.0a9	Actual value of PINNED_RUNTIME_VERSION
5	CLI-only v0.1.28/29 releases	Unchanged runtime value 0.2.0a9
6	CLI 0.1.30 pairing	Minimum version and host/CLI compatibility relationship
7	Developer handle claiming	INVALID_HANDLE, HANDLE_TAKEN, and SLUG_FROZEN
8	Verified-developer identity	Install-dialog contents and reserved first-party @anna namespace
9	Bare-slug cutover	HTTP 400, INVALID_APP_REF, and the correct replacement form
10	Realtime NATS delivery	JetStream backfill and reconnect reliability guarantee
11	beta.53 wire-protocol pins	Concrete anna-app-schema and local-runtime versions
12	Namespaced publishing compatibility	Host + CLI 0.1.30 pairing requirement
13	beta.54/55 pin matrix	Schema, local-runtime, and CLI values
14	Markdown content negotiation	?format=md method
15	Host API and landing-page refresh	Landing-page refresh cannot be verified; welcome.md predates the changelog by eight weeks
16	Compatibility-section pin restatement	Three non-dispatcher version values
17	speedPriority	Measured fast, balanced, and thorough latency tiers
18	Binary mirroring	Explicit statement that release is blocked until every binary is mirrored
19	Immutable ExecutaVersion snapshot	Guarantee that install, reinstall, and upgrade all resolve from it
20	Deployment reconciliation	Retriable executa_not_deployed error
21	Upload response alignment	Canonical-to-legacy alias table; bytes_size introduces a third spelling
22	APS cross-app access	aps.scope.app.write; Storage currently says cross-owner writes are not_implemented
23	Unknown methods return -32601	Host → app backward-compatibility behavior
24	Client versions for new capabilities	Required CLI 0.1.38 and app-runtime 0.13.0

A recurring pattern is that the documentation explains a mechanism but omits its current version, compatibility boundary, error code, or reliability guarantee.

---

Internal Documentation Contradictions

#	Contradiction	Severity
1	host-api-files.md says APS capabilities are not consulted, while its method entries require aps.scope.app.read.	High
2	The APS per-value KV limit is 64 KB in one section and 256 KB in another.	High
3	Generated-image URL lifetime is one hour in a tutorial and about 30 minutes in the reference.	Medium
4	A quickstart says Executa has no SDK, while another page uses SDK examples throughout.	Medium
5	An example declares schema: 1 while containing UI and Host API ACL fields, although schema 1 is documented as having no UI.	Medium
6	Files documents cross-app access as supported, while Storage says it is not_implemented.	Medium
7	Upload size is size_bytes in the canonical table but bytes_size in the app response.	High
8	Eight reference pages say manifest.permissions is never checked, while the decision guide calls it the permission model.	High
9	Upload error -32211 means different things on two pages.	Medium
10	Agent reverse-RPC error tables disagree on six of eight code assignments.	High
11	EXECUTA_KEEP_VERSIONS defaults to 1 on one page and 2 on another.	Medium
12	A tutorial calls anna.agent.refresh(...), while the reference requires anna.agent.session.refresh(...).	High
13	The AgentSession handle-method list omits .refresh().	Medium
14	Per-turn system prompt is system on the Executa side and systemPrompt on the Host API side, although the docs say both sides are interchangeable.	Medium
15	One page says three plugin identity names must match; another says the Agent no longer reads the self-declared name.	High
16	The FAQ says credentials reach plugins through environment variables; the credentials reference says invocation context.	High
17	The FAQ says an administrator sets developer handles; the CLI reference documents a self-service command.	Medium
18	RPC parameter tables omit app_session_uuid, while the reference says every agent.session.* method requires it.	High
19	agent.session.refresh has three different parameter sets across the docs, plus a fourth in the changelog.	High

It may be safer to designate one canonical source for each contract and generate or validate secondary pages against it.

---

llms.txt and llms-full.txt Issues

1. 36 of 84 index entries have no description

All 36 affected entries are API reference pages. Each page already contains a usable description source, but the index generator does not extract it when frontmatter is absent.

With frontmatter    → title + description
Without frontmatter → title only

Suggested fix: when frontmatter has no description, use the first body paragraph that is neither a heading nor a block quote.

2. reference.md has the wrong index title

Index: Reference index
Page:  Anna Developer Reference

This is the only title mismatch among 84 entries.

3. llms.txt contains two ## Reference sections

63:## Reference
68:## Reference

The first contains two entries with descriptions and frontmatter. The second contains 36 entries without descriptions or frontmatter.

Suggested fix: merge the sections after fixing description extraction, or rename the second section to ## API Reference.

4. Markdown readers cannot discover llms-full.txt

The literal string llms has zero matches across all 84 Markdown pages, llms.txt, and llms-full.txt. References to /llms.txt and /llms-full.txt exist only in HTML shells.

An agent entering through a .md page therefore has no way to discover the full-corpus artifact.

Suggested fix: add a one-line link to /llms-full.txt in the introduction of llms.txt.

Additional coverage issue

reference.md is the only documentation page omitted from llms-full.txt: all 36 long body lines from that page are absent.

---

Suggested Fix Order

1. Correct the stale slug rules, asset URLs, quotas, publishing behavior, and version matrix.

2. Resolve high-severity contradictions affecting permissions, error codes, field names, credentials, and API contracts.

3. Add the nine completely missing developer-facing behaviors.

4. Create one authoritative package and host compatibility matrix.

5. Fill the 24 partial gaps, prioritizing error codes and version requirements.

6. Fix the llms.txt generator and add llms-full.txt discovery.

7. Add a release-time documentation check for current pins, limits, error codes, and changelog claims.

Audit Notes

• All 78 changelog items received a second input-isolated review, and disagreements were adjudicated individually.

• “Not documented” findings were based on corpus search and targeted page reading.

• Thirty-six API reference pages have no updated field, so their freshness cannot be assessed reliably by date alone.

• This audit compares changelogs with documentation, not documentation with live platform behavior. I did not have a platform account available to test implementation behavior directly.

I hope this is useful. The main request is not simply for more prose, but for a small number of authoritative and internally consistent contracts, especially for version compatibility, permissions, error codes, field names, and namespaced app identity. Secondary pages and agent-facing indexes could then be generated or validated against those contracts.