docs: update md and agent files

Author: kusssal

AGENTS.md

@@ -18,7 +18,7 @@ tests/AGENTS.md: E2E, API and load suites
   wallet connection and transaction building. Main surface.
 - govtool/backend: Haskell + Servant, read-only REST over cardano-db-sync. All
   endpoints, db-sync queries, response shapes.
-- govtool/metadata-validation: NestJS. Rules for what makes CIP-100/108/119 off-chain
+- govtool/metadata-validation: NestJS. Rules for what makes CIP-108/119 off-chain
   metadata valid.
 - govtool/analytics-dashboard: Next.js internal usage dashboard. Not part of the
   gov.tools user flow; touch only when asked about analytics.

docs/ai/ARCHITECTURE_MAP.md

@@ -20,8 +20,7 @@ builds with cardano-serialization-lib and the wallet signs.
 
 Vite aliases: @ for src, plus @pages @consts @context @hooks @models @services @utils
 @mock, and @atoms @molecules @organisms for src/components/*. There is no @types or
-@config alias, so use @/types/... and @/config/env. Every folder has an index.ts
-barrel and new files must be added to it.
+@config alias, so use @/types/... and @/config/env. Many feature directories expose files through index.ts barrels. When a directory already uses a barrel, add new public exports to it; otherwise follow the surrounding direct-import pattern.
 
 - App.tsx: the route table. Every route registers here.
 - config/env.ts: the only env accessor. Reads window.__ENV__, then import.meta.env.
@@ -30,8 +29,10 @@ barrel and new files must be added to it.
 - consts/queryKeys.ts: QUERY_KEYS and MUTATION_KEYS. Every new key registers here.
 - consts/governanceAction/fields.ts: GA form schemas, driving both rendering and
   hashing
-- services/API.ts: the single axios instance, with the 500-to-error-page interceptor
-- i18n/locales/en.json: all user-facing copy, about 925 lines, the only locale
+- services/API.ts:is the shared Axios instance for the GovTool backend and redirects backend HTTP 500 responses to the error
+  page.Metadata validation uses a separate Axios client because it has a separate base URL.
+- i18n/locales/en.json: is the only locale and should be the source of new user-facing copy. Some existing hardcoded strings
+  remain.
 - components: atomic design. atoms have no GovTool dependencies, molecules compose
   atoms without fetching, organisms are feature blocks that may use contexts and hooks.
 
@@ -46,9 +47,8 @@ Contexts in src/context:
   vote totals show for which GA type
 - pendingTransaction: in-flight txs, so the UI can poll /transaction/status/:txId
 - governanceAction.tsx: GA list and detail state
-- contextProviders.tsx composes all of them. modal, snackbar, pagination and
-  dataActionsBar are UI plumbing; adaHandle, usersnap and proposalDiscussion are
-  integrations.
+- contextProviders.tsx: composes the main application providers. ChatwootProvider is mounted separately in main.tsx, and 
+  pending-transaction state is integrated through the wallet context.
 
 ## govtool/backend
 
@@ -91,34 +91,105 @@ into SQL and cache the result rather than holding a connection.
 
 ## govtool/metadata-validation
 
-NestJS. One job: fetch metadata at a URL, canonize the JSON-LD, hash it, validate the
-body against a CIP standard. POST /validate is in app.controller.ts, orchestration in
-app.service.ts, rules in utils/getStandard.ts, utils/validateCIP108body.ts and
-utils/validateMetadataStandard.ts. enums/ValidationError.ts holds the error codes the
-frontend switches on, so grep the frontend before renaming one.
+A NestJS service that validates off-chain metadata. It fetches metadata from a URL,
+parses the JSON, accepts a supplied CIP standard or attempts to identify CIP-108 or
+CIP-119, validates the required fields for a recognized standard, and compares a
+Blake2b-256 hash of the exact fetched content with the submitted hash.
 
-utils/canonizeJSON.ts is duplicated at govtool/frontend/src/utils/canonizeJSON.ts and
-must behave identically: the frontend hashes metadata before submission and this
-service re-hashes it. Change one, change both.
+POST /validate is defined in app.controller.ts, orchestration is handled by
+app.service.ts, and validation logic lives in utils/getStandard.ts,
+utils/validateCIP108body.ts, and utils/validateMetadataStandard.ts.
+enums/ValidationError.ts defines the validation statuses consumed by the frontend,
+so check frontend usage before renaming or removing one.
+
+Both metadata validation and the frontend contain utils/canonizeJSON.ts. The
+metadata-validation copy is currently unused by the production validation flow. The
+frontend uses canonicalization for signature verification, not for the metadata hash submitted to POST /validate.
 
 ## Environment variables
 
-Frontend. .env.example, src/config/env.ts and docker-entrypoint.sh must all agree.
-
-- VITE_BASE_URL: backend REST base URL
-- VITE_METADATA_API_URL: metadata-validation service
-- VITE_PDF_API_URL, VITE_OUTCOMES_API_URL: pillar APIs
-- VITE_IPFS_GATEWAY, VITE_IPFS_PROJECT_ID: IPFS reads
-- VITE_NETWORK_FLAG: Cardano network id, 0 is testnet
-- VITE_APP_ENV, VITE_IS_DEV: environment banners and dev affordances
-- VITE_IS_PROPOSAL_DISCUSSION_FORUM_ENABLED,
-  VITE_IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED: pillar flags
-- VITE_SENTRY_DSN, VITE_GTM_ID, VITE_USERSNAP_SPACE_API_KEY
-
-Backend. example-config.json, or the same keys as env vars via Conferer:
-dbsyncconfig with host, dbname, user, password and port; port 9999; host;
-cachedurationseconds; dreplistcachedurationseconds; pinataapijwt; sentrydsn;
-sentryenv.
+### Frontend application configuration
+
+The frontend reads configuration from window.__ENV__ when running in a container,
+falling back to Vite's import.meta.env values for local development and build-time
+configuration.
+
+When adding a frontend runtime variable, update all applicable configuration points:
+
+1. govtool/frontend/.env.example
+2. govtool/frontend/src/config/env.ts
+3. govtool/frontend/docker-entrypoint.sh
+4. The govtool-frontend service in docker/docker-compose.yaml
+
+Active frontend variables:
+
+- VITE_BASE_URL: GovTool backend REST API base URL.
+- VITE_METADATA_API_URL: metadata-validation service base URL.
+- VITE_PDF_API_URL: Proposal Discussion and Budget Discussion API base URL.
+- VITE_OUTCOMES_API_URL: Governance Outcomes API base URL.
+- VITE_IPFS_GATEWAY: gateway used to resolve ipfs:// resources.
+- VITE_IPFS_PROJECT_ID: optional project identifier sent when accessing the
+  configured IPFS gateway.
+- VITE_NETWORK_FLAG: Cardano network ID; 0 selects a test network and 1
+  selects mainnet.
+- VITE_APP_ENV: deployment environment name supplied to services such as Sentry.
+- VITE_IS_DEV: enables development behavior, including React Query devtools and
+  bypassing production maintenance checks.
+- VITE_IS_PROPOSAL_DISCUSSION_FORUM_ENABLED: enables the Proposal Discussion
+  pillar.
+- VITE_IS_GOVERNANCE_OUTCOMES_PILLAR_ENABLED: enables the Governance Outcomes
+  pillar.
+- VITE_SENTRY_DSN: optional Sentry data source name.
+- VITE_CHATWOOT_URL: base URL from which the Chatwoot SDK is loaded.
+- VITE_CHATWOOT_WEBSITE_TOKEN: Chatwoot website token used to initialize the
+  feedback widget.
+
+### Frontend container and analytics configuration
+The frontend container also accepts variables that are handled by
+docker-entrypoint.sh and Nginx rather than exposed to React through window.__ENV__:
+
+- UMAMI_URL: base URL of the Umami analytics service.
+- UMAMI_WEBSITE_ID: Umami website identifier.
+- UMAMI_SSL_VERIFY: controls TLS certificate verification for the Umami proxy;
+  defaults to true.
+- TRUSTED_PROXY_CIDRS: trusted proxy address ranges used when resolving the
+  original client IP. Set it to none to disable real-IP resolution.
+- REAL_IP_HEADER: header used to obtain the original client IP; defaults to
+  X-Forwarded-For.
+
+Umami is enabled only when both UMAMI_URL and UMAMI_WEBSITE_ID are configured.
+
+### Metadata-validation service
+
+The metadata-validation service reads these variables directly from process.env:
+
+- PORT: HTTP port used by the NestJS service.
+- IPFS_GATEWAY: gateway used to resolve ipfs:// metadata URLs.
+- IPFS_PROJECT_ID: optional project identifier sent to the configured IPFS
+  gateway.
+
+The local template is govtool/metadata-validation/.env.example.
+
+### Backend configuration
+
+The Haskell backend loads configuration from example-config.json, or from the file
+supplied with --config / -c. Conferer also supports environment-variable overrides
+prefixed with VVA_.
+
+Backend configuration keys:
+
+- dbsyncconfig.host: cardano-db-sync PostgreSQL host.
+- dbsyncconfig.dbname: database name.
+- dbsyncconfig.user: database user.
+- dbsyncconfig.password: database password.
+- dbsyncconfig.port: PostgreSQL port.
+- port: backend HTTP port; example-config.json uses 9999.
+- host: backend bind address.
+- cachedurationseconds: default endpoint-cache lifetime in seconds.
+- dreplistcachedurationseconds: DRep-list cache lifetime in seconds.
+- pinataapijwt: optional Pinata API JWT used by the IPFS upload endpoint.
+- sentrydsn: backend Sentry data source name.
+- sentryenv: backend Sentry environment name.
 
 ## CI gates, in .github/workflows
 

docs/ai/PLAYBOOKS.md

@@ -29,14 +29,29 @@ useGetProposalQuery, keyed on [key, dRepID, proposalId]. Return a named object l
    Dashboard element route gets connected chrome, wrapped in PublicRoute redirects
    when a wallet is connected.
 
-Keep the page thin. It wires hooks to organisms; markup belongs in organisms.
+Route placement controls layout and connected variants, but does not by itself define
+all access requirements:
+
+- Public browsing routes are registered at the top level.
+- Routes nested under Dashboard receive the connected dashboard layout.
+- PublicRoute currently redirects public DRep-directory routes to their
+  /connected equivalents when a wallet is connected.
+- Wallet-dependent transaction pages, including registration and governance-action
+  creation, are currently top-level routes and enforce their requirements through
+  their page and wallet logic.
+Keep the page thin. It should wire hooks and state to feature components; follow the
+surrounding page and organism structure.
 
 ## Frontend: add a component
 
-The only real decision is the layer. atoms for anything with no GovTool dependencies,
-molecules for compositions of atoms that do not fetch, organisms for feature blocks
-that may use contexts and query hooks. Add a .stories.tsx if it is reusable, since
-Storybook builds in CI.
+Choose the existing component layer whose responsibilities most closely match the new
+component. The atoms, molecules and organisms directories express increasing feature
+composition, but the boundaries are not strict: existing atoms and molecules may use
+shared hooks or contexts. Match nearby components before introducing a new layering
+rule.
+For a reusable component, add or update a Storybook story under src/stories, using
+.stories.ts or .stories.tsx depending on whether the story contains JSX.
+Storybook build and interaction tests run in CI.
 
 ## Frontend: add user-facing copy
 
@@ -46,14 +61,21 @@ t("key", { name }). No hardcoded strings in JSX.
 
 ## Frontend: add an environment variable
 
-Real only once it is in all four:
+A new React-visible `VITE_` runtime variable is complete only after updating all four
+applicable configuration points:
 
 1. .env.example
 2. src/config/env.ts, as MY_VAR: getEnv("VITE_MY_VAR")
-3. docker-entrypoint.sh, into the window.__ENV__ block. This is the forgotten one:
-   skip it and the var is undefined in every container while working locally.
+3. docker-entrypoint.sh, into the window.__ENV__ block. 
 4. docker/docker-compose.yaml, passed into the govtool-frontend service
 
+The entrypoint is easy to miss: without runtime injection, a variable may work through
+import.meta.env during local development but be undefined in a deployed container.
+
+Container-only variables such as Umami and Nginx proxy configuration do not belong in
+src/config/env.ts or window.__ENV__; document and wire those through
+docker-entrypoint.sh and Compose instead.
+
 ## Frontend: add a feature flag
 
 In src/context/featureFlag.tsx: add to FeatureFlagContextType, the createContext
@@ -65,20 +87,34 @@ predicate; exemplar areDRepVoteTotalsDisplayed.
 
 ## Frontend: build a new transaction or certificate
 
-All of it lives in src/context/wallet.tsx. Add a buildXCert or
-buildXGovernanceAction beside its siblings, hand the certificates to
-buildSignSubmitConwayCertTx which owns builder, UTxO selection, change address,
-signing and submit, expose it on the context value, and register the result with
-pendingTransaction so the UI can poll /transaction/status/:txId.
+Shared Cardano serialization, wallet interaction and transaction submission live in
+src/context/wallet.tsx. Form-specific validation and selection of the appropriate
+builder remain in the calling form hook or page.
+
+Add the appropriate builder beside its siblings:
+- buildXCert for certificates
+- buildXGovernanceAction for governance-action proposal builders
+- A voting builder for votes
+
+Expose the builder through CardanoContextType and the provider value. Pass the
+result to buildSignSubmitConwayCertTx through the matching argument:
+certBuilder, govActionBuilder or votingBuilder.
+
+buildSignSubmitConwayCertTx owns maintenance checks, UTxO selection, change,
+signing, submission and pending-transaction registration. Supply the correct
+transaction type and, when applicable, resourceId; it records the submitted hash
+so usePendingTransaction can poll /transaction/status/:txId.
 
 Extend an existing builder rather than adding a parallel path, and verify on a
 testnet. This code moves real ada and has no unit tests.
 
 ## Frontend: write a unit test
 
-Utils go in src/utils/tests/util.test.ts importing from the barrel, as from "..".
-Everything else is co-located, e.g. context/featureFlag.test.tsx. Iterate with
-npx vitest run and a path. Coverage comes from components, consts, context, hooks,
+Utils go in src/utils/tests/<utility>.test.ts and normally import the
+utility from the parent barrel with from "..". Other tests are generally colocated
+with the code under test, for example context/featureFlag.test.tsx.
+
+Run a focused test with npx vitest run <path>.Coverage comes from components, consts, context, hooks,
 services and utils; pages and models are excluded, so do not chase coverage there.
 
 ## Backend: add a REST endpoint
@@ -101,18 +137,18 @@ tests/govtool-backend/test_cases.
 
 ## Backend: add caching to an endpoint
 
-Two edits plus the call site: a field on CacheEnv in src/VVA/Types.hs, its
-initialisation in the cacheEnv block in app/Main.hs using newCache for the standard
-TTL or newDRepListCache for the long one, then in the handler:
+Add a field to CacheEnv in src/VVA/Types.hs, initialize it in the cacheEnv
+block in `app/Main.hs`, and use it at the handler call site.
+
+Use newCache for the standard configured TTL. Use the DRep-list TTL only when the
+endpoint is deliberately intended to share that longer cache duration; rename or add
+a dedicated constructor binding when introducing another cache category.
 
 ```haskell
 CacheEnv {myThingCache} <- asks vvaCache
 cacheRequest myThingCache cacheKey $ do ...
 ```
 
-The key must include every parameter affecting the result. cacheRequest needs
-Hashable; compound keys use hash or hashWithSalt.
-
 ## Backend: change a db-sync query
 
 Change a SELECT list and you must change the domain function's
@@ -124,26 +160,45 @@ db-sync instance, and say so if you could not.
 ## Add a new governance action type
 
 docs/operations/HANDLE_NEW_GOVERNANCE_ACTION_TYPE.md covers this but its paths and
-line numbers are stale. Current locations:
-
-1. src/types/governanceAction.ts: the GovernanceActionType member, any new field type,
-   a schema extending SharedGovernanceActionFieldSchema, and that schema added to the
-   GovernanceActionFieldSchemas union
-2. src/consts/governanceAction/fields.ts: the field declaration, meaning component,
-   labelI18nKey, placeholderI18nKey, tipI18nKey and rules. The doc says
-   src/constants/governanceActionFields.ts, which does not exist.
-3. src/i18n/locales/en.json: every key the schema references
-4. Custom validation, if any: a helper in src/utils such as numberValidation.ts or
-   isValidFormat.ts, used as validate in rules. The doc's
-   src/utils/govActionValidations does not exist.
-5. src/context/featureFlag.tsx: how the type behaves in bootstrap versus full
-   governance. Skipping this is how a new type ships silently unvotable.
-6. src/context/wallet.tsx: a buildXGovernanceAction if it needs a new certificate
-
-Verify at /create_governance_action, then fix the ops doc, which asks you to. The
-schema drives both rendering in CreateGovernanceActionForm.tsx and hashing and
-validation in useCreateGovernanceActionForm.ts, so getting it right is most of the
-work. Actions must comply with CIP-100 and CIP-108.
+line numbers are stale.A genuinely new governance-action type can affect both frontend and backend.
+
+Frontend locations:
+
+1. src/types/governanceAction.ts: add the GovernanceActionType member, field
+   types, schema extending SharedGovernanceActionFieldSchema, and the schema union
+   member.
+2. src/consts/governanceAction/fields.ts: define the fields, meaning components,
+   i18n keys and validation rules.
+3. src/consts/governanceAction/filters.ts: add the type when it should appear in
+   governance-action filters.
+4. src/i18n/locales/en.json: add every label, placeholder, tip, error and display
+   key used by the new type.
+5. src/utils: add any custom validation and update exhaustive mappings such as
+   getGovActionVotingThresholdKey.ts.
+6. src/context/featureFlag.tsx: define voting and vote-total behavior for bootstrap
+   and full-governance phases.
+7. src/context/wallet.tsx: add the Cardano serialization builder and expose it
+   through the wallet context.
+8. src/hooks/forms/useCreateGovernanceActionForm.ts: add the new type to the
+   buildTransaction switch and construct the builder arguments.
+9. Update details rendering, tests and Storybook fixtures wherever behavior differs
+   by governance-action type.
+
+Backend locations:
+
+1. src/VVA/API/Types.hs: add the type to GovernanceActionType. This affects JSON,
+   query-parameter parsing and the OpenAPI enum.
+2. Review src/VVA/API.hs filtering, response conversion and enacted-details logic
+   for type-specific mappings.
+3. Update backend API tests and response examples that enumerate or assume the
+   existing action types.
+
+Verify creation at /create_governance_action, backend filtering and response
+decoding, voting behavior, details rendering and protocol phase visibility.Add
+frontend unit tests and backend/E2E coverage where applicable.
+Actions must comply with CIP-100 and CIP-108.
+Afterward, update the stale operations document rather than preserving conflicting
+paths.
 
 ## Change metadata validation rules