[WIP] docs: enforce Architecture.md integrity and document public API surface

[descorp]

Summary

• Strengthen AGENTS.md so docs/Architecture.md is kept in sync with code (not just reviewed before refactoring): added an "update in the same PR" rule for directory structure, class hierarchies, core interfaces, configuration hierarchy, embedded bus contracts, and event/error/result codes, plus an integrity-validation step (grep every documented symbol, remove stale entries).
• Add a new ## Public API section to AGENTS.md declaring src/index.ts re-exports as the contractual API and governing add/remove/rename of exports as breaking changes.
• Add a standalone docs/PublicAPI.md enumerating every symbol re-exported through the four barrels (components, core, hooks, modules), grouped by category, with an "Internal (not exported)" section listing symbols that must stay internal (session, embedded bus, base wrappers, internal helpers).
• Update the Verification Checklist: item 7 now requires docs/PublicAPI.md to be updated and example/ usages fixed on public API changes; new item 8 requires docs/Architecture.md update + integrity validation when structure/hierarchy/interfaces/configs/codes change.

No ticket — docs-only change to agent guidance and API documentation.

Test plan

• docs/PublicAPI.md cross-checked against src/index.ts and the four barrels (src/components/index.ts, src/core/index.ts, src/hooks/index.ts, src/modules/index.ts) — every listed export resolves, and internal symbols (session, embedded, base) are correctly excluded.
• AGENTS.md renders correctly (markdown structure, no broken references).
• No code or test changes — yarn test / yarn lint / yarn typecheck not affected.

[gemini-code-assist]

Code Review

This pull request updates AGENTS.md with new refactoring conventions and public API guidelines, and introduces docs/PublicAPI.md to serve as the canonical source of truth for the package's public API surface. The review feedback points out inaccuracies in docs/PublicAPI.md regarding how configurations are exported (they are exported as both types and values, not just types) and notes that the source paths in the configurations table are missing the core/ prefix.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The description states "Re-exported (as types)", but src/core/index.ts exports configurations using export * from './configurations'; which exports both types and values. Additionally, this section exports the GooglePayEnvironment enum, which is a runtime value.\n\nFurthermore, the source paths in the table below (lines 66-107) are missing the core/ prefix (e.g., configurations/Configuration.ts instead of core/configurations/Configuration.ts). They should be updated to be relative to src/ to maintain consistency with the rest of the document.

[descorp]

Fixed in commit 7acae296 — two changes:

1. Paths: Added the core/ prefix to all source paths in the Configurations table (e.g. core/configurations/Configuration.ts) for consistency with the rest of the document.

2. Type-only clarification: Verified empirically with tsc that the configurations barrel (src/core/configurations/index.ts) uses export type *, so all configuration symbols — including GooglePayEnvironment — are type-only and cannot be used as runtime values. The compiler confirms this: error TS1362: 'GooglePayEnvironment' cannot be used as a value because it was exported using 'export type'. The section description now explicitly states this, and GooglePayEnvironment is marked as enum (type-only) in the table.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud