# Anna Developer Reference Feedback: 12 Documentation Issues in the PACKAGES and PLATFORM APIS Sections **URL:** \ **Category:** Developers\ **Created:** [June 12, 2026, 4:36pm UTC](https://forum.anna.partners/t/anna-developer-reference-feedback-12-documentation-issues-in-the-packages-and-platform-apis-sections/99 "2026-06-12T16:36:39Z")\ **Posts on this page:** 2\ **Page:** 1
**Author:** ![HappyLight](https://avatars.discourse-cdn.com/v4/letter/h/7feea3/32.png) [@HappyLight](https://forum.anna.partners/u/HappyLight)\ **Post date:** [June 12, 2026, 4:36pm UTC](https://forum.anna.partners/t/anna-developer-reference-feedback-12-documentation-issues-in-the-packages-and-platform-apis-sections/99/1 "2026-06-12T16:36:39Z")
Hi Anna team, I reviewed the Anna Developer Reference page: > **[Reference — Anna Developer Hub](https://staging.anna.partners/developers/reference)** > > Anna Developer Reference — every capability, host-API method, manifest field, and event you can ship against. 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](https://staging.anna.partners/developers/reference/packages) 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](https://staging.anna.partners/developers/reference/cli) 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](https://staging.anna.partners/developers/reference/cli) 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](https://staging.anna.partners/developers/reference/cli) 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](https://staging.anna.partners/developers/reference/cli) Issue: The `executa dev — discovery` section says Node uses `npm run start` or `node
`, 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 `, 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](https://staging.anna.partners/developers/reference/cli) 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](https://staging.anna.partners/developers/reference/cli) 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](https://staging.anna.partners/developers/reference/rest-developer) 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](https://staging.anna.partners/developers/reference/rest-developer) 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](https://staging.anna.partners/developers/reference/rest-developer) 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](https://staging.anna.partners/developers/reference/lifecycle) 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](https://staging.anna.partners/developers/reference/lifecycle) 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. ---
**Author:** ![hunter](https://yyz1.discourse-cdn.com/flex033/user_avatar/forum.anna.partners/hunter/32/8_2.png) [@hunter](https://forum.anna.partners/u/hunter)\ **Post date:** [June 15, 2026, 10:22am UTC](https://forum.anna.partners/t/anna-developer-reference-feedback-12-documentation-issues-in-the-packages-and-platform-apis-sections/99/2 "2026-06-15T10:22:49Z")
Hi @HappyLight 👋 Thank you so much for this incredibly thorough review — cross-checking against your installed CLI, the source, and the example repo is exactly the kind of feedback that makes the docs better for everyone. 🙏✨ Great news: the **PACKAGES** and **PLATFORM APIS** content has been consolidated into a single **Build & Distribute** section, and we’ve just pushed fixes for the issues you raised. Here’s where things landed: ### ✅ Fixed - **#1 Package names** — You’re absolutely right. The published packages are `@anna-ai/app-runtime` and `@anna-ai/app-schema` (npm), plus `anna-app-core`, `anna-app-runtime-local`, `anna-app-schema`, and `anna-executa-test` (PyPI). The old `@anna-app/*` names and the npm/PyPI tags are now corrected. 📦 - **#3 `--executa` overrides** — Clarified: `dir=` alone auto-discovers, but the moment you pass `type=` or `command=`, `tool_id=` is required too. 🔧 - **#4 Go discovery** — Updated: `go.mod` alone errors out; a Go Executa needs an `executa.json` with `tool_id` + `type: "go"`. - **#5 Node startup** — Corrected to `node ` (`bin[tool_id]` → first `bin` → `main` → `module`); `npm run start` is never auto-run. - **#6 / #7 Sampling & Agent defaults** — Reworded so `--no-sampling` / `--no-agent` read as _forced-off_ modes, and the real default falls back to disabled only when there’s no mock, no `--app-slug`, and no usable account. 🎯 - **#11 Executa visibility** — Now lists the actual enum `private / app_bundled / public` and explains that `executa publish` targets `app_bundled` by default. `unlisted` and `paid` were not real values, so they’ve been removed. 🏷 - **#12 Lifecycle flow** — Added a cross-reference to the working-draft flow (`apps push` → `apps cut` → `apps release`) so the relationship to App status is clearer. ### 📝 Already addressed - **#2 `apps:list`** — The docs already use the correct `anna-app apps list` form (with a note that it replaces the old `apps:list`). ### ℹ A small note - **#8 / #9 / #10** — These targeted the standalone REST `/api/v1/developer` page, which has since been folded into the consolidated **Build & Distribute** section, so those specific page paths no longer exist in the current docs. If you spot any remaining endpoint-namespace confusion in the new layout, we’d love a follow-up. 🙌 These changes should be live on staging shortly. Please keep the reports coming — reviews like this genuinely help us ship better docs for the whole developer community. Happy building! 🚀💛