Hi Anna team,
I reviewed the Anna Developer Reference page:
My review focused on the PACKAGES and PLATFORM APIS sections. I cross-checked the documentation against my locally installed @anna-ai/cli@0.1.29, CLI help output, the globally installed CLI package source, and the example repository.
Below are 12 documentation issues I found for your review.
1. Packages Reference: package names may not match the actual published package names
Page: Reference — Anna Developer Hub
Issue: The page lists @anna-app/core, @anna-app/runtime, @anna-app/runtime-local, and @anna-app/schema, but my locally installed @anna-ai/cli@0.1.29 actually depends on @anna-ai/app-runtime and @anna-ai/app-schema.
Impact: Developers may try to install or search for @anna-app/* packages and find that they do not match the packages currently used by the CLI.
Suggestion: Please confirm whether the packages have migrated from @anna-ai/* to @anna-app/*. If this is the new naming scheme, it would be helpful to add a migration note or package name mapping. If not, the page should use the current published package names.
2. CLI Reference: incorrect apps:list command format
Page: Reference — Anna Developer Hub
Issue: In the Auth & accounts section, the page lists apps:list, but the actual CLI command is anna-app apps list.
Impact: Developers may copy or search for the wrong command. Running anna-app apps:list results in unknown command 'apps:list'.
Suggestion: Change it to apps list, or use the full command anna-app apps list.
3. CLI Reference: --executa parameter description is not accurate enough
Page: Reference — Anna Developer Hub
Issue: The page describes tool_id=, type=, and command= in --executa dir=... as optional overrides. However, in the local CLI, if type= or command= is explicitly provided, tool_id= is also required.
Impact: Developers may write --executa dir=...,type=go or --executa dir=...,command=... based on the docs, but the command will fail with a missing tool_id= error.
Suggestion: Clarify that auto-discovery applies when only dir= is provided. If type= or command= is provided, tool_id= must also be provided.
4. CLI Reference: Go auto-discovery description for executa dev is incorrect
Page: Reference — Anna Developer Hub
Issue: The executa dev — discovery section says that a Go project with go.mod will automatically use go run ., but the local CLI actually requires an explicit executa.json for Go Executas.
Impact: Developers may assume that a Go project with only go.mod can be run automatically with anna-app executa dev, but it will fail.
Suggestion: Update the docs to say that go.mod alone will fail and that a Go Executa requires an executa.json with tool_id and type: "go".
5. CLI Reference: Node startup rule for executa dev is incorrect
Page: Reference — Anna Developer Hub
Issue: The executa dev — discovery section says Node uses npm run start or node <main>, but the local CLI does not automatically run npm run start.
Impact: Developers may think that defining scripts.start is enough for auto-discovery, but the CLI may not find a usable entry point.
Suggestion: Update the rule to match the actual behavior: node <bin[tool_id] | first bin | main | module>, and clarify that npm run start is not automatically executed.
6. CLI Reference: default sampling behavior for executa dev is inaccurate
Page: Reference — Anna Developer Hub
Issue: The executa dev — sampling section marks --no-sampling as default off and says every reverse call returns sampling_disabled (-32008) by default. However, the local CLI enters real sampling mode when an account or appSlug is available.
Impact: Readers may think sampling is always disabled by default, instead of understanding that it falls back to disabled only when no mock, account, or app slug is available.
Suggestion: Clarify that sampling falls back to disabled when there is no --mock-sampling and no usable dev app/account. --no-sampling should be described as a forced disabled mode.
7. CLI Reference: default agent behavior for executa dev is inaccurate
Page: Reference — Anna Developer Hub
Issue: The executa dev — agent section marks --no-agent as default off and says every reverse call returns agent_not_granted (-32041) by default. However, the local CLI enters real agent mode when an account and appSlug are available.
Impact: Readers may think the agent API is always disabled by default, instead of understanding that it falls back to disabled only when no mock, account, or app slug is available.
Suggestion: Clarify that agent mode falls back to disabled when there is no --mock-agent and no usable dev app/account. --no-agent should be described as a forced disabled mode.
8. REST Reference: Auth/token endpoint namespace is inaccurate
Page: Reference — Anna Developer Hub
Issue: The page header says REST · /API/V1/DEVELOPER, but Auth & sessions / token endpoints are not actually under the /api/v1/developer namespace.
Impact: Developers may interpret the page as saying these endpoints are relative to /api/v1/developer, which could lead them to construct incorrect URLs.
Suggestion: Mark dev auth/token endpoints separately as /api/v1/anna-apps/dev/*, or explicitly state that these endpoints are not relative to /api/v1/developer/*.
9. REST Reference: GET /dev/apps may be confused with the official App list endpoint
Page: Reference — Anna Developer Hub
Issue: The page describes GET /dev/apps as “List Apps owned by the developer”, but anna-app apps list actually requests /api/v1/developer/apps.
Impact: This can confuse the local dev app registration/cache query endpoint with the developer publishing lifecycle App list endpoint.
Suggestion: If this is describing anna-app apps list, it should be GET /developer/apps. If /dev/apps is kept, clarify that it belongs to the local dev harness registration flow.
10. REST Reference: Executa skills versions endpoint needs confirmation
Page: Reference — Anna Developer Hub
Issue: The page lists POST /executas/my/{tools|skills}/{id}/versions, but the local CLI only shows a versions endpoint for tools, not for skills.
Impact: If skill versions are not currently supported, this may incorrectly suggest that tools and skills both support the same versions endpoint.
Suggestion: Please confirm whether the server supports skill versions. If not, the docs should use POST /executas/my/tools/{id}/versions, or explicitly state that {skills} is not currently exposed by the CLI.
11. Lifecycle Reference: Executa visibility values do not match the CLI
Page: Reference — Anna Developer Hub
Issue: The page lists private / unlisted / public / paid, but the local CLI uses app_bundled as the default non-public visibility target for executa publish. The page does not list app_bundled.
Impact: Developers may not understand why executa publish produces app_bundled visibility, and may also assume unlisted or paid can be set through the current CLI.
Suggestion: Add the current actual visibility values, such as private / app_bundled / public, and confirm whether unlisted and paid are still valid states. If they are future-facing or not exposed by the current CLI, please label them accordingly.
12. Lifecycle Reference: Anna App lifecycle does not reflect the current recommended publishing flow
Page: Reference — Anna Developer Hub
Issue: The page only lists the App states draft -> pending_review -> approved/rejected -> published -> archived, but it does not describe the current CLI-recommended working draft flow.
Impact: Developers may miss the current recommended flow: apps push -> apps cut -> submit-review/release. It can also blur the distinction between App status, working draft, and immutable App versions.
Suggestion: Add the relationship between working drafts, cut versions, and release, or link to the CLI documentation for apps push, apps cut, and apps release.
These findings are based on the current staging documentation and my locally installed @anna-ai/cli@0.1.29. If some of the documented behavior targets an upcoming version, it would be helpful to add version notes, migration notes, or a clear statement of what is supported by the current CLI.
Fixed
Already addressed
A small note
