[anth-volk]

Fixes #113
Fixes #114

Summary

The Public API (api.policyengine.org) is becoming callable only by PolicyEngine's own servers. This adds policyengine-api-access, a skill that tells dashboard developers and agents how to reach it: from pages through www.policyengine.org's dashboard API and @policyengine/api-client, and from servers with their own Auth0 client-credentials token. It also stops the existing skills, agents and commands telling browser code to call the Public API, and points them to the new skill.

@policyengine/api-client 0.1.0, which the skill tells dashboards to install, is on npm: it was published by hand on 2026-11-10 from PolicyEngine/policyengine-app-v2 main at 6030be089 (licence MIT, dist-tag latest). That commit includes #1543, so the published client polls as the skill describes.

The guidance changes were first opened as #117 and now merge here, with the skill they point to. The CI check script once planned for dashboards (#118, #115) is dropped; its branch public-api-access-check is kept.

Changes: the new skill

• skills/policyengine-api-access/SKILL.md:
  • The rules: browser code never calls api.policyengine.org or the Public API's Cloud Run addresses; no Public API credential or address goes in a NEXT_PUBLIC_* or VITE_* variable; one Auth0 client per calling server.
  • Which route to use: pages, backends, CI jobs and Python analysis.
  • From pages: the four dashboard operations with their request and answer shapes and validation, @policyengine/api-client usage, economy-comparison polling, the origins the dashboard API accepts, and its rate limits as the Vercel firewall applies them since 2026-11-10: over a limit it answers 429 itself, as text/plain, with no Retry-After and no CORS headers, so a page on another origin sees a network failure. The polling text follows the client as merged with @policyengine/api-client: wait out the firewall's 429 while polling policyengine-app-v2#1543 (RATE_LIMIT_WAIT_MILLISECONDS), which the published 0.1.0 includes.
  • From servers: the production and staging tenants, audiences and variables; the token request; Authorization, PolicyEngine-User-Authorization and PolicyEngine-Unauthenticated-User; caching tokens across instances on Modal, Vercel and CI; no redirects; and the steps for getting a client onto PUBLIC_API_SERVER_CLIENT_IDS before any token is sent.
  • Local development and previews, asking for a new dashboard operation, and a table of the dashboard API's and the Public API's errors, including 401, 403, 429 and 503.
• skills/policyengine-api-access/templates/public_api_token.py: a copyable Python token cache for Modal backends, Cloud Run services and scripts. It keeps one token in memory and in a store the instances share (a modal.Dict on Modal) until five minutes before it expires, raises a 401 without requesting another token (a new one would be refused too and use up the tenant's monthly allowance), never follows redirects, and never stores the client secret. It uses only the standard library.
• The skill is in the analysis-tools (which the create-dashboard workflow installs), api-development, app-development, complete and dashboard-builder bundles and in the catalog. The plugin version moves from 4.1.0 to 4.2.0 in every bundle and the marketplace template.
• dashboard/src/data/manifest.json is rebuilt with uv run python scripts/build_manifest.py: the new skill, its five bundle edges and overlap entries, and the bundles' version and skill lists. The rebuild also picks up Stop the data skill steering agents to microimpute and uk-data #108's unbuilt change to policyengine-data's description and target repositories. tests/pipeline/test_when_to_use_guide.py reads skill IDs from this file, so docs/when-to-use.md, which now names the skill, needs it. It is rebuilt again at 74182b7, 95936b4 and 2e751e5 for the changed skills, agents and command: their descriptions, sizes and references, and new edges to policyengine-api-access.

Changes: the existing skills, agents and commands

• skills/policyengine-api: says who may call v1 (servers with their own credential) and that pages use the dashboard API; drops "JS frontends" from when to use REST; lists /health and /v2/openapi.json instead of /specification and the liveness and readiness checks, which the Public API removed (policyengine_api/migration_flags.py).
• skills/policyengine-tools: Pattern B is the dashboard API through @policyengine/api-client, with its four operations. A Pattern C backend that calls the Public API needs its own client and cached token; one that runs policyengine in its own process needs neither.
• skills/policyengine-app: the calculator's direct browser calls through BASE_URL are moving to app.policyengine.org's own route, /api/policyengine/{Public API path}, which forwards only the operations in app/src/libs/publicApiRoute/allowList.ts. New calculator code goes through that route.
• targets/claude/agents/dashboard/backend-builder.md and targets/claude/commands/new-tool.md: the Pattern B client wraps @policyengine/api-client instead of fetching https://api.policyengine.org. The types are type aliases, because the client takes Record<string, unknown> and a TypeScript interface is not assignable to it.
• The dashboard planner, scaffold, integrator and backend-builder load policyengine-api-access and describe Pattern B by what the dashboard API offers. The data_pattern value stays policyengine-api, so existing plan.yaml files still validate.
• The policyengine skill, targets/codex/agents/policyengine-app-v2/AGENTS.md and docs/when-to-use.md point to policyengine-api-access; the guide's catalog counts are current (25 skills).

Sources

Every path, shape, header, origin rule and error comes from merged code:

• PolicyEngine/policyengine-app-v2 main at 6030be089, the commit @policyengine/api-client 0.1.0 was published from (it includes #1533 and #1543): website/src/app/api/, website/src/lib/dashboardApi/ (operations.ts, cors.ts, handler.ts), packages/public-api-forwarding/ (settings.ts, accessToken.ts, cors.ts, responses.ts), packages/api-client/, and app/src/models/household/pythonPackageCodec.ts for the axes shape.
• PolicyEngine/policyengine-api main at 2073325a: policyengine_api/request_caller.py (the credential check runs on every route, /health included), policyengine_api/libs/server_credentials.py, policyengine_api/routes/household_routes.py and services/household_calculation_service.py (/calculate adds no omitted variables, and accepts axes), and docs/migration/stage-12a-user-login.md (the user routes' 401).

Left as they are

These call the Public API outside a browser: from an agent's shell, or from this repository's analyze-policy and create-dashboard workflows on GitHub Actions. None sends a credential, so each stops working once the credential requirement is on:

• targets/claude/agents/microsim-runner.md: Python requests to /us/policy, /us/economy/… and …/budget-window (its default "API path"); the analyze-policy workflow runs it through /analyze-policy.
• targets/claude/commands/create-dashboard.md: in headless runs, the precomputed pattern fetches impacts with POST /us/policy and the economy endpoints, without naming the host.
• targets/claude/agents/dashboard/dashboard-planner.md: for the precomputed pattern, a /calculate sweep over the lever inputs at build time.
• targets/claude/commands/analyze-policy.md: checks a parameter's deployed value through the metadata endpoint and probes /calculate.
• targets/claude/agents/model-corroborator.md: curl to /us/policy and /us/economy/….
• targets/claude/agents/parameter-locator.md: curl to /us/metadata.
• targets/claude/commands/text-to-reform.md: names the Public API as where a user might submit a reform.
• dashboard/src/pages/Guides.tsx: guide text describing microsim-runner's API path; it makes no request.
• analyses/*.md: dated records, kept as written.

Not in this PR

• Dashboard guidance that disagrees with itself but doesn't send browser code to the Public API, found in review rounds 2 and 3: the frontend-builder agent, and the integrator's Step 4 example for a custom backend, use a useHouseholdSimulation hook that backend-builder doesn't export (it exports useCalculation); /deploy-dashboard adds a dashboard's rewrites to website/next.config.ts, while the dashboard API's allowed origins come from website/src/data/appZoneRoutes.ts; and the planner's household-page rule ("Hybrid compute (the NJ pattern)") sends custom household inputs to a Modal backend rather than Pattern B. Each needs a decision about the dashboard workflow, so they are left for a follow-up.

• policyengine.org/us/ai-agents shows the catalog's counts from website/src/app/[countryId]/ai-agents/pluginStats.json in app-v2. After this merges, skills goes from 24 to 25 there, in an app-v2 PR.

• Open: where developers ask for a new dashboard operation and for a server client. The skill says an issue in PolicyEngine/policyengine-app-v2 and "the Public API's maintainers"; this waits for a decision.

Tests

The skill

tests/test_api_access_skill.py checks the frontmatter; the five bundles, the catalog and the wrapper build; that the skill names the four operations, the client's exports, the server headers, tenants, audiences and variables, the 401, 503 and 403 bodies, the allowed origins, and a row for each of 401, 403, 429 and 503. tests/test_public_api_browser_guidance.py checks every skill, this one included, for browser-language examples that name the Public API and for public-prefix variables that hold its address or a credential. The template's tests use a fake opener and a dict as the shared store: one token serves many requests and both instances, it is replaced five minutes before expiry, a 401 is raised on every call without another token request, a redirected token request becomes an error and stores nothing, partial settings are refused, a local server's 307 is not followed, a failing shared store does not stop it, a short token is replaced halfway through its life, the settings' repr hides the secret, and the Opener Protocol takes the request by position and the timeout by keyword.

• Red, e84b09c: 53 failed on their assertions, 1 passed (the pattern self-test); exit code 1.
• Green, 9e63be7: 54 passed; exit code 0. The green commit also registers the template module in sys.modules in the test loader, which dataclasses needs.
• The firewall's 429 (added after the rules went live): red 5e0fbc1, where tests/test_api_access_skill.py::test_skill_describes_the_dashboard_api_firewall_refusal failed on its assertion (exit code 1); green e8cf0af, 55 passed (exit code 0).
• Review round 1's findings: red a139568, where test_template_raises_a_refused_request_without_requesting_another_token, test_skill_describes_the_dashboard_api_firewall_refusal and test_errors_table_tells_a_refused_server_token_from_a_refused_user_token failed on their assertions (exit code 1); green 7e325d3, all 74 tests in tests/test_api_access_skill.py and tests/test_public_api_browser_guidance.py passed (exit code 0).
• The manifest: red 00261a0, where tests/test_api_access_skill.py::test_dashboard_manifest_lists_the_skill failed on its assertion (exit code 1); green 9ac72ca, 56 passed (exit code 0).
• CI: red 42886437907 at 00261a0: tests/test_api_access_skill.py::test_dashboard_manifest_lists_the_skill failed on its assertion, 1 failed and 263 passed; green 42886481119 at 9ac72ca: both jobs passed. The earlier commits were pushed before the PR existed, so their red runs are the local ones above.

The anti-rot lint's checks pass on every changed file. The wrapper build ships skills/policyengine-api-access/SKILL.md and the template.

The existing guidance

tests/test_public_api_browser_guidance.py: TypeScript and JavaScript examples in skills/, targets/ and docs/ may not name a Public API host (the household API and v2 hosts are not matched); no NEXT_PUBLIC_ or VITE_ variable may be set to one or named like a credential; eleven files that guide dashboard and app work must point to policyengine-api-access; the API skill's public routes; and the tools skill's Pattern B.

• Red, 29b87d2: 15 failed on their assertions, 2 passed (no public-prefix violations existed, and the patterns' self-test); exit code 1.
• Green, b6f3e85: 17 passed; exit code 0.
• Review round 3's findings: red 703a72a, where seven tests in the two new test files failed on their assertions (exit code 1), among them tests/test_public_api_browser_guidance.py::test_calculated_household_is_read_through_a_typed_helper and tests/test_api_access_skill.py::test_template_opener_protocol_takes_the_request_positionally_and_timeout_by_keyword; green 2e751e5, all 89 tests in the two files passed (exit code 0).
• Type checks, run locally at 2e751e5: the TypeScript in backend-builder's Pattern B and the integrator's Steps 4 and 6 compiles together under strict (TypeScript 5.9) against @policyengine/api-client's source at 6030be089, and the old result.households.household… read fails there with TS18046; the token template passes mypy --strict.
• Review round 2's findings: red 68e4eaa, where eight tests in the two new test files failed on their assertions (exit code 1), among them tests/test_api_access_skill.py::test_template_modal_wiring_adds_the_module_to_the_image and tests/test_public_api_browser_guidance.py::test_integrator_varies_a_household_in_one_calculation; green 95936b4, all 83 tests in the two files passed (exit code 0), after the skill's test module dropped three checks that duplicated the guard.
• Review round 1's findings: red f69d880, where tests/test_public_api_browser_guidance.py::test_guards_catch_the_patterns_they_name, ::test_dashboard_scaffold_loads_the_access_skill and ::test_custom_backend_guidance_agrees_with_what_the_dashboard_api_offers failed on their assertions (exit code 1); green 74182b7, all 77 tests in the two new test files passed (exit code 0). The guard now also covers ~~~ and longer fences, HTML, Vue and Svelte blocks, nested blocks, JSON keys, || fallbacks and Cloud Run's per-project addresses, and accepts a browser's own Auth0 sign-in settings.
• CI: these changes were first opened as Send dashboard and app guidance through the dashboard API, not the Public API #117, whose run 42885835654 failed tests/pipeline/test_when_to_use_guide.py::test_skills_section_references_real_skills, because the guide names policyengine-api-access and the dashboard manifest had not been rebuilt. The manifest commits above fix it.

🤖 Generated with Claude Code