diff --git a/.agents/commands/sdd-full-bootstrap.md b/.agents/commands/sdd-full-bootstrap.md
new file mode 100644
index 0000000..ff86d5d
--- /dev/null
+++ b/.agents/commands/sdd-full-bootstrap.md
@@ -0,0 +1,65 @@
+# SDD Full Bootstrap — pickup-points-modal
+
+Use this command when starting a **new feature** on this repo that requires the Full SDD flow.
+
+## When to use Full SDD
+
+- Any new user-facing feature or behavioral change in `react/`.
+- Changes to the public component API (`PickupPointsModal.js` props, events, `orderForm` shape).
+- Changes that touch `manifest.json`, `package.json`, or CI pipelines.
+- All work on `main`-targeted branches (not hotfix branches).
+
+**Lite-only is allowed** for hotfixes on `fix/*` or `chk-*` branches. See `sdd-lite-bootstrap.md`.
+
+## Pipeline
+
+```
+/speckit-specify   → generates specs/<feature>/spec.md
+/speckit-plan      → generates specs/<feature>/plan.md
+/speckit-tasks     → generates specs/<feature>/tasks.md
+/speckit-implement → executes tasks in code
+/speckit-analyze   → audits consistency between spec/plan/tasks/code
+```
+
+Or use the higher-level skill aliases:
+
+```
+/specification  → Business Context + Arch Decisions + Technical Contract (spec.md)
+/implementing   → Implement from an approved spec up to the PR
+```
+
+## Before starting
+
+1. Read `AGENTS.md` — verified commands, autonomy limits, sources of truth.
+2. Read `.specify/memory/constitution.md` — binding principles.
+3. Confirm the Jira/GitHub issue exists and acceptance criteria are clear.
+4. Run `yarn install` from repo root.
+
+## Verified commands
+
+```bash
+yarn lint          # ESLint over js,jsx,ts,tsx
+yarn lint:ts       # tsc --noEmit
+yarn lint:locales  # intl-equalizer (i18n key parity)
+yarn test          # Jest on react/
+yarn test:coverage # Jest with coverage report
+yarn build         # Production build (lib/ + locales)
+```
+
+## Files that require human approval before touching
+
+- `manifest.json` — version, dependencies, builders.
+- `package.json` — dependencies, scripts, engines.
+- `react/PickupPointsModal.js` — root component (public API).
+- `react/ModalState.js` — root state manager.
+- `.travis.yml`, `.github/**`, `.vtex/deployment.yaml` — CI/CD.
+- `CHANGELOG.md` bumps and `vtex publish` / `npm publish`.
+
+## Quality gates before opening PR
+
+- [ ] `yarn lint` passes (0 errors).
+- [ ] `yarn lint:ts` passes (0 type errors).
+- [ ] `yarn lint:locales` passes (all locale files in sync).
+- [ ] `yarn test` passes (all existing tests green).
+- [ ] New behavior covered by at least one Jest test.
+- [ ] `spec.md` approved before implementation starts.
diff --git a/.agents/commands/sdd-lite-bootstrap.md b/.agents/commands/sdd-lite-bootstrap.md
new file mode 100644
index 0000000..69b008d
--- /dev/null
+++ b/.agents/commands/sdd-lite-bootstrap.md
@@ -0,0 +1,49 @@
+# SDD Lite Bootstrap — pickup-points-modal
+
+Use this command for **hotfixes** on `fix/*` or `chk-*` branches where Full SDD would be excessive overhead.
+
+## When Lite is allowed
+
+- Bug fixes with a clear, contained scope (no public API change).
+- Branch name starts with `fix/` or `chk-`.
+- Change touches fewer than 3 files in `react/components/` or `react/utils/`.
+- No changes to `manifest.json`, root components, or CI.
+
+For everything else, use the Full SDD flow (`sdd-full-bootstrap.md`).
+
+## Pipeline
+
+```
+/specification  → creates a lightweight spec.md (Business Context + Technical Contract)
+/implementing   → implements from the approved spec up to the PR
+```
+
+## Before starting
+
+1. Read `AGENTS.md` — verified commands, autonomy limits, sources of truth.
+2. Confirm the bug is reproducible and the fix scope is clear.
+3. Run `yarn install` from repo root.
+
+## Verified commands
+
+```bash
+yarn lint          # ESLint over js,jsx,ts,tsx
+yarn lint:ts       # tsc --noEmit
+yarn lint:locales  # intl-equalizer (i18n key parity)
+yarn test          # Jest on react/
+yarn test:coverage # Jest with coverage report
+```
+
+## Files that require human approval even on hotfix branches
+
+- `manifest.json` — version bump.
+- `react/PickupPointsModal.js` — public API surface.
+- `react/ModalState.js` — root state manager.
+- `.travis.yml`, `.github/**` — CI/CD.
+
+## Quality gates before opening PR
+
+- [ ] `yarn lint` passes (0 errors).
+- [ ] `yarn lint:ts` passes (0 type errors).
+- [ ] `yarn test` passes (all tests green).
+- [ ] Reproducing test added (failing before fix, green after).
diff --git a/.agents/rules/00-baseline.md b/.agents/rules/00-baseline.md
new file mode 100644
index 0000000..47d470a
--- /dev/null
+++ b/.agents/rules/00-baseline.md
@@ -0,0 +1,61 @@
+---
+name: pickup-points-modal-baseline
+description: Baseline rules every agent must follow when editing this repo.
+applyTo: "**/*"
+---
+
+# Baseline Rules — pickup-points-modal
+
+## Stack
+
+- **App:** `vtex.pickup-points-modal` — VTEX IO React component for checkout.
+- **Source:** `react/` (no `node/` builder). Legacy JS + TypeScript coexist.
+- **Test runner:** Jest via `vtex-test-tools` (`yarn test` from repo root).
+- **Linter:** ESLint with `eslint-config-vtex` (root) and `eslint-config-vtex-react` (`react/`).
+- **Formatter:** Prettier with `@vtex/prettier-config`.
+- **Type checker:** `tsc --noEmit -p react/tsconfig.json`.
+
+## Verified commands (always run from repo root)
+
+```bash
+yarn install          # install all dependencies first
+yarn lint             # ESLint — must pass before any PR
+yarn lint:ts          # TypeScript check — must pass before any PR
+yarn lint:locales     # i18n key parity check — must pass before any PR
+yarn test             # Jest test suite — must pass before any PR
+yarn test:coverage    # Jest with coverage
+yarn format           # Prettier auto-fix
+yarn build            # production build
+```
+
+## Autonomy limits
+
+**May modify freely:**
+- `react/components/`, `react/containers/`, `react/utils/`, `react/fetchers/`, `react/types/`
+- Tests: `react/**/__tests__/`, `react/**/*.test.{js,ts,tsx}`
+- Messages: `messages/` — add keys to ALL locale files in the same PR
+
+**Must ask for human approval:**
+- `manifest.json` (version, dependencies, builders)
+- `package.json` (dependencies, scripts, engines)
+- `.travis.yml`, `.github/**`, `.vtex/deployment.yaml` (CI/CD)
+- `react/PickupPointsModal.js` or `react/ModalState.js` (root/public API)
+- Any publish action: `vtex publish`, `npm publish`, `CHANGELOG.md` bump
+
+**Must never:**
+- Run `git push --force` on `main` or skip hooks with `--no-verify`
+- Commit secrets, `.env*` files, or Google Maps keys
+- Remove tests to unblock a build
+- Mock `orderForm` in integration tests — use `react/__mocks__/` fixtures
+
+## SDD flow
+
+- **Default:** Full SDD for all features (see `.agents/commands/sdd-full-bootstrap.md`)
+- **Lite-only:** hotfixes on `fix/*` or `chk-*` branches (see `.agents/commands/sdd-lite-bootstrap.md`)
+
+## Sources of truth (priority order)
+
+1. `.specify/memory/constitution.md` — binding principles
+2. `README.md` — public API and props
+3. `CONTRIBUTING.md` — PR flow and changelog rules
+4. `manifest.json` — published version and VTEX IO dependencies
diff --git a/.agents/rules/10-react.md b/.agents/rules/10-react.md
new file mode 100644
index 0000000..46a3075
--- /dev/null
+++ b/.agents/rules/10-react.md
@@ -0,0 +1,43 @@
+---
+name: pickup-points-modal-react
+description: Rules scoped to the React source in react/ — component conventions, testing, i18n, and public API gate.
+applyTo: "react/**/*"
+---
+
+# React Source Rules — pickup-points-modal
+
+## Component conventions
+
+- **Class components** are legacy — prefer functional components with hooks for new code.
+- **PropTypes** are required on all new components alongside TypeScript types (dual-declaration pattern already used in the codebase).
+- Container components live in `react/containers/`; pure UI in `react/components/`.
+- Side effects and I/O belong in `react/fetchers/` or `react/containers/`, never inside utility functions in `react/utils/`.
+- Utility functions must be pure (no I/O, no singletons). Name I/O functions explicitly: `fetchX`, `saveY`, or suffix with `Event` for telemetry (see `react/utils/metrics.js`).
+
+## Testing expectations
+
+- Test files live in `react/**/__tests__/` or next to source as `*.test.{js,ts,tsx}`.
+- Every behavioral change must be accompanied by at least one Jest test covering the new behavior.
+- Use `react/__mocks__/` fixtures for `orderForm` and VTEX IO module mocks — do not create new inline mocks for these.
+- Snapshot tests (`.snap`) are in `react/components/__tests__/__snapshots__/` — update them intentionally, never blindly.
+
+## Internationalization (non-negotiable)
+
+- Every user-facing string must use `react-intl` (`<FormattedMessage>` or `intl.formatMessage`).
+- New i18n keys must be added to **all** locale files in `messages/` in the same PR.
+- `messages/context.json` is the English master — new keys go here first.
+- Run `yarn lint:locales` before opening any PR that touches `messages/`.
+
+## Public API gate
+
+`react/PickupPointsModal.js` is the public contract consumed by production VTEX stores.
+
+- Any prop addition, removal, or shape change is **breaking** and requires a major version bump in `manifest.json`.
+- Changes to this file require human approval and an explicit `CHANGELOG.md` entry.
+- The Google Maps gated load in `react/containers/withGoogleMaps.js` must not be bypassed.
+
+## Performance rules
+
+- No unconditional network requests on initial render without cache or debounce.
+- No heavy library imports in the main bundle without justification in the PR description.
+- PRs that increase bundle size must explain the cost and loading strategy.
diff --git a/.agents/skills/implementing/SKILL.md b/.agents/skills/implementing/SKILL.md
new file mode 100644
index 0000000..5ea8000
--- /dev/null
+++ b/.agents/skills/implementing/SKILL.md
@@ -0,0 +1,56 @@
+---
+name: implementing
+description: Implement an approved spec end-to-end in the pickup-points-modal repo — branch, code, tests, lint, typecheck, build, commit, and open a PR following Conventional Commits and the project constitution.
+type: skill
+---
+
+# implementing
+
+Use this skill when the user says "implement it", "implement this spec",
+"implement specs/<feature>.md", or asks for autonomous execution from an
+already-approved spec.
+
+## Prerequisites
+
+- `specs/<feature>/spec.md` exists and is approved by the user.
+- Constitution has been read
+  ([.specify/memory/constitution.md](../../../.specify/memory/constitution.md)).
+- AGENTS.md has been read for autonomy limits.
+
+If any of these is missing, **stop** and ask the user to run the
+`specification` skill first.
+
+## Flow
+
+1. **Branch.** `git checkout -b feat/<feature-slug>` (use `fix/<slug>`
+   for bug fixes, `chore/<slug>` for tooling).
+2. **Break into tasks.** List 3–8 concrete tasks in TodoWrite.
+3. **Implement task by task.**
+   - For each task: edit files → run `yarn lint --fix` → run
+     `yarn test` in the affected scope → mark task complete.
+   - Never skip tests. Principle 2 of the constitution.
+4. **Lint & types.** Run `yarn lint` and `yarn lint:ts` before
+   committing.
+5. **i18n.** If a visible string was added, run `yarn lint:locales`.
+   Principle 3 of the constitution.
+6. **Build.** `yarn build` must pass.
+7. **Commit.** Use `speckit-git-commit` to format Conventional Commits.
+8. **PR.** Open with `gh pr create`, linking the spec, principles
+   affected, and manual test plan.
+
+## Autonomy limits
+
+See [AGENTS.md](../../../AGENTS.md). In short:
+
+- **Do not touch** `manifest.json`, `package.json`, `.travis.yml`,
+  `.github/`, `.vtex/deployment.yaml` without explicit confirmation.
+- **Do not publish.** `vtex publish` and `npm publish` are manual.
+- **Do not force-push** to a branch that already has an open PR.
+
+## When to pause and report
+
+Pause and report back to the user when:
+
+- The build fails in a way that suggests a dependency range change.
+- Typecheck flags an issue in code you did not touch.
+- A product/UX decision is not covered by the spec.
diff --git a/.agents/skills/specification/SKILL.md b/.agents/skills/specification/SKILL.md
new file mode 100644
index 0000000..7dd328b
--- /dev/null
+++ b/.agents/skills/specification/SKILL.md
@@ -0,0 +1,58 @@
+---
+name: specification
+description: Generate an SDD (Spec Driven Development) document for a new feature in the pickup-points-modal, covering Business Context, Architectural Decisions, and Technical Contract before any code is written.
+type: skill
+---
+
+# specification
+
+Use this skill when the user asks to "create a spec", "write an SDD", or
+references a file under `specs/`. The deliverable is a
+`specs/<feature-slug>/spec.md` file with three mandatory sections.
+
+## When to use
+
+- New feature that touches the public contract of `PickupPointsModal`.
+- Architectural change (new container, new state flow).
+- Refactor with cross-cutting impact (i18n, fetchers, map).
+
+**Do not use** for a one-off bug fix or a styling tweak — go straight to
+`implementing` or `speckit-git-commit`.
+
+## Deliverable structure
+
+```markdown
+# Spec: <feature>
+
+## Business Context
+- Problem being solved
+- Stakeholders (who asked, who is impacted)
+- Success metrics
+
+## Architectural Decisions
+- Components/files affected
+- Alternatives considered + why they were dropped
+- Backward-compatibility risk (cite Principle 1 of the constitution)
+
+## Technical Contract
+- Changes to props/events
+- Changes to fixtures/mocks
+- Test plan (golden path + edge cases)
+- i18n plan (new keys, locales touched)
+- Verifiable acceptance criteria
+```
+
+## Expected inputs
+
+- Natural-language description of the feature.
+- Link to a Jira/issue ticket if one exists.
+- List of suspected files (if the user has already investigated).
+
+## How to apply
+
+1. Read [.specify/memory/constitution.md](../../../.specify/memory/constitution.md)
+   to understand binding principles.
+2. Read [AGENTS.md](../../../AGENTS.md) for autonomy limits.
+3. Sketch the 3 sections with `TBD` markers where input is missing.
+4. Present the draft to the user before creating the final file.
+5. Do not implement anything — spec only.
diff --git a/.agents/skills/speckit-analyze/SKILL.md b/.agents/skills/speckit-analyze/SKILL.md
new file mode 100644
index 0000000..ca11a46
--- /dev/null
+++ b/.agents/skills/speckit-analyze/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: speckit-analyze
+description: Audit consistency between spec.md, plan.md, tasks.md, and the actual code in the pickup-points-modal — flagging drift, missing tasks, or out-of-spec changes before PR review.
+type: skill
+---
+
+# speckit-analyze
+
+Lightweight audit before opening the PR. Detects drift across the four
+artifacts: spec → plan → tasks → code.
+
+## When to use
+
+- After `speckit-implement` and before `gh pr create`.
+- When the spec author is different from the implementer.
+- Before requesting human review on a large feature.
+
+## Checks
+
+1. **Spec → Plan:** does every acceptance criterion from the spec
+   appear as an item in the plan?
+2. **Plan → Tasks:** does every file listed under "Files to touch"
+   have at least one task?
+3. **Tasks → Code:** is every file modified in `git diff` covered by
+   some task?
+4. **Constitution check:** does the diff respect the 5 principles?
+
+## Output
+
+A markdown report listing:
+
+- ✅ Items in sync
+- ⚠️ Drift (changed in code but not in the task/spec)
+- ❌ Missing (acceptance criterion without implementation)
+
+It does not fix anything — it only reports. The user decides whether to
+update spec/plan or revert the code.
+
+## Important
+
+`speckit-analyze` is **read-only**. It never edits the spec, plan,
+tasks or code. If drift is found, it returns the report and stops.
diff --git a/.agents/skills/speckit-checklist/SKILL.md b/.agents/skills/speckit-checklist/SKILL.md
new file mode 100644
index 0000000..b20ed91
--- /dev/null
+++ b/.agents/skills/speckit-checklist/SKILL.md
@@ -0,0 +1,52 @@
+---
+name: speckit-checklist
+description: Generate a per-feature validation checklist (pre-merge gates, manual QA steps, rollback plan) for a pickup-points-modal feature, tailored to the spec and constitution principles.
+type: skill
+---
+
+# speckit-checklist
+
+Generates a validation checklist to drop into the PR description or
+into `specs/<slug>/checklist.md`. Not generic — it is derived from the
+spec and the constitution principles.
+
+## When to use
+
+- Before requesting human review.
+- On features touching checkout-critical paths.
+
+## Structure
+
+```markdown
+# Checklist — <feature>
+
+## Pre-merge gates
+- [ ] `yarn lint` passes
+- [ ] `yarn lint:ts` passes
+- [ ] `yarn test` passes
+- [ ] `yarn lint:locales` passes (if i18n was touched)
+- [ ] `yarn build` passes
+- [ ] CHANGELOG updated if the change is user-visible
+
+## Constitution checks
+- [ ] Principle 1: public contract preserved or major bump
+- [ ] Principle 2: tests cover golden path + edge case
+- [ ] Principle 3: new keys present in every locale
+- [ ] Principle 4: no bundle/TTI regression
+- [ ] Principle 5: new utilities are pure
+
+## Manual QA
+- [ ] Scenario <X> tested in the demo (`yarn start`)
+- [ ] Works with empty `searchAddress`
+- [ ] Works with 0 pickup points returned
+- [ ] Works in `pt-BR` and `en-US` locales
+
+## Rollback plan
+- Branch revertable? <yes/no>
+- Data migration? <yes/no>
+- Feature flag? <name>
+```
+
+## Template
+
+See [.specify/templates/checklist-template.md](../../../.specify/templates/checklist-template.md).
diff --git a/.agents/skills/speckit-clarify/SKILL.md b/.agents/skills/speckit-clarify/SKILL.md
new file mode 100644
index 0000000..652995f
--- /dev/null
+++ b/.agents/skills/speckit-clarify/SKILL.md
@@ -0,0 +1,41 @@
+---
+name: speckit-clarify
+description: Interactively clarify ambiguous requirements in a spec.md before planning — generates targeted questions for the requester to resolve TBDs in the pickup-points-modal feature spec.
+type: skill
+---
+
+# speckit-clarify
+
+Generates focused questions to unblock a spec with TBDs or ambiguities.
+Runs between `speckit-specify` and `speckit-plan`.
+
+## When to use
+
+- `spec.md` has 2+ `TBD` markers in required fields.
+- Vague acceptance criteria ("it should just work well").
+- A stakeholder was not explicit about edge cases.
+
+## Flow
+
+1. Read `specs/<slug>/spec.md`.
+2. Identify gaps in:
+   - Business Context (who, why, metric)
+   - Architectural Decisions (alternatives, risks)
+   - Technical Contract (props, fixtures, i18n, acceptance)
+3. Generate **at most 5 questions** per iteration, ordered by impact.
+4. Wait for user replies.
+5. Update `spec.md` with the answers — preserve history under a
+   `## Clarifications` section at the end of the file.
+
+## Good questions
+
+- Specific: "Should the modal close when a pickup is chosen? Before or
+  after the confirm step?"
+- Actionable: the answer changes the plan.
+- Unique: not already answered earlier in the spec.
+
+## Bad questions
+
+- "Anything else?"
+- "What do you think?"
+- Questions the agent could answer by reading the code.
diff --git a/.agents/skills/speckit-constitution/SKILL.md b/.agents/skills/speckit-constitution/SKILL.md
new file mode 100644
index 0000000..3e7e215
--- /dev/null
+++ b/.agents/skills/speckit-constitution/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: speckit-constitution
+description: Create or amend the project constitution in .specify/memory/constitution.md, capturing binding principles, governance, and ratification metadata for the pickup-points-modal.
+type: skill
+---
+
+# speckit-constitution
+
+Use to create or edit `.specify/memory/constitution.md`. This file is the
+**binding source of truth** — it overrides any other doc in case of
+conflict.
+
+## When to use
+
+- First time creating the constitution.
+- Adding a new principle (minor bump).
+- Revoking or rewriting a principle (major bump).
+- Updating governance rules.
+
+## Required structure
+
+```markdown
+# <Project> — Project Constitution
+
+**Version** X.Y.Z | **Ratified** YYYY-MM-DD | **Last Amended** YYYY-MM-DD
+
+## Principles
+### 1. <Principle name>
+- Why: ...
+- How to apply: ...
+
+## Governance
+- Who ratifies
+- How to propose a change
+- Versioning (SemVer)
+- Audit cadence
+```
+
+## Rules
+
+- **No placeholders.** No `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`, etc.
+  left in the final file.
+- **Version line always present.** The review script (item 9) greps for
+  `**Version** ... **Ratified**`.
+- **Concrete principles.** Each one has real `Why` and `How to apply` —
+  empty bullets will fail item 1b downstream.
+
+## Template
+
+See [.specify/templates/constitution-template.md](../../../.specify/templates/constitution-template.md).
diff --git a/.agents/skills/speckit-git-commit/SKILL.md b/.agents/skills/speckit-git-commit/SKILL.md
new file mode 100644
index 0000000..03f5441
--- /dev/null
+++ b/.agents/skills/speckit-git-commit/SKILL.md
@@ -0,0 +1,61 @@
+---
+name: speckit-git-commit
+description: Compose Conventional Commits messages and stage the right files for a pickup-points-modal change, respecting CHANGELOG and the constitution's backward-compat principle.
+type: skill
+---
+
+# speckit-git-commit
+
+Compose commit messages in the repo's Conventional Commits style.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Accepted types
+
+| Type | When to use |
+|---|---|
+| `feat` | User-visible feature |
+| `fix` | Bug fix |
+| `chore` | Tooling/deps without functional change |
+| `docs` | Documentation change (README, CHANGELOG, AGENTS) |
+| `refactor` | Refactor without functional change |
+| `test` | Tests only |
+| `perf` | Performance improvement |
+
+### Suggested scopes
+
+- `modal` — `PickupPointsModal.js`, `ModalState.js`
+- `map` — Google Maps components
+- `i18n` — `messages/`
+- `fetchers` — `react/fetchers/`
+- `tooling` — config files
+
+## Rules tied to the constitution
+
+- **Breaking change** in `PickupPointsModal` props/events:
+  - Add `BREAKING CHANGE:` in the footer.
+  - Major bump in `manifest.json` (ask first).
+  - CHANGELOG entry.
+
+- **i18n change:** scope `i18n` and list the locales touched in the body.
+
+## Staging
+
+- Always stage by specific path (`git add react/components/X.js`),
+  **never** `git add -A` or `git add .` — those can pull in `.env*` or
+  build artifacts.
+- Confirm with `git status` before committing.
+
+## Don't
+
+- `--no-verify` to skip hooks.
+- Subject in uppercase.
+- Subject longer than 72 chars.
diff --git a/.agents/skills/speckit-git-feature/SKILL.md b/.agents/skills/speckit-git-feature/SKILL.md
new file mode 100644
index 0000000..1431ddd
--- /dev/null
+++ b/.agents/skills/speckit-git-feature/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: speckit-git-feature
+description: Create a new git feature branch following the pickup-points-modal naming convention (feat/<slug>, fix/<slug>, chore/<slug>) from latest origin/main.
+type: skill
+---
+
+# speckit-git-feature
+
+Creates a feature branch following the repo's naming convention.
+
+## When to use
+
+- At the start of any non-trivial work.
+- Before `speckit-implement`.
+
+## Naming convention
+
+| Prefix | When to use |
+|---|---|
+| `feat/<slug>` | User-visible new feature |
+| `fix/<slug>` | Bug fix |
+| `chore/<slug>` | Tooling, docs, deps without functional change |
+| `refactor/<slug>` | Refactor without functional change |
+| `chk-<ticket>` | Checkout team Jira ticket (`chk-NNNN` format) |
+
+`<slug>` is kebab-case, descriptive, max 5 words.
+
+## Flow
+
+```sh
+git fetch origin
+git checkout -b feat/<slug> origin/main
+```
+
+## Validations
+
+- Current branch before creating: ideally `main` or `origin/main`.
+- Working tree clean: anything pending? Stash or commit first.
+- Branch with the same slug exists? Surface it and ask.
+
+## Don't
+
+- Don't create a branch off another feature branch that has not been
+  merged yet.
+- Don't use `master` (the repo uses `main`).
+- Don't force-push to a branch that already has an open PR.
diff --git a/.agents/skills/speckit-implement/SKILL.md b/.agents/skills/speckit-implement/SKILL.md
new file mode 100644
index 0000000..bf6568d
--- /dev/null
+++ b/.agents/skills/speckit-implement/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: speckit-implement
+description: Execute the tasks.md generated by speckit-tasks, running lint/typecheck/tests per task and surfacing blockers, ending with a PR-ready branch for the pickup-points-modal.
+type: skill
+---
+
+# speckit-implement
+
+Execution of the tasks listed in `tasks.md`. Structured variant of the
+`implementing` skill, tied to the Full Golden Path.
+
+## When to use
+
+- `specs/<slug>/tasks.md` approved.
+- The user says "/speckit-implement" or "execute the tasks".
+
+## Flow
+
+For each task in `tasks.md`:
+
+1. Mark it as `in_progress` in TodoWrite.
+2. Read the relevant files.
+3. Edit.
+4. Run `yarn lint --fix` in scope.
+5. Run `yarn test` over the affected scope.
+6. Mark as `completed`. Only one task `in_progress` at a time.
+
+When all tasks are done:
+
+- `yarn lint` globally
+- `yarn lint:ts`
+- `yarn lint:locales` if i18n was touched
+- `yarn test`
+- `yarn build`
+- Compose commits with `speckit-git-commit`
+- Open the PR
+
+## Signals to pause and report
+
+- A previously-passing test starts failing outside of the task's scope.
+- Lint complains about a file you did not touch (likely a rule change —
+  surface it before mass-fixing).
+- `yarn build` fails due to types in legacy JS code — escalate.
+
+## Constitution gates
+
+Before opening the PR, validate:
+
+| Principle | Check |
+|---|---|
+| 1 — backward-compat | `PickupPointsModal` public props/events unchanged (or major bump documented). |
+| 2 — tested behavior | Each behavior task has a new test. |
+| 3 — i18n | `yarn lint:locales` passes. |
+| 4 — performance | No new dep > 50KB without dynamic import. |
+| 5 — side-effect free | New utilities are pure. |
diff --git a/.agents/skills/speckit-plan/SKILL.md b/.agents/skills/speckit-plan/SKILL.md
new file mode 100644
index 0000000..7d0da78
--- /dev/null
+++ b/.agents/skills/speckit-plan/SKILL.md
@@ -0,0 +1,49 @@
+---
+name: speckit-plan
+description: Break an approved spec.md into a technical plan.md listing files to touch, execution order, risks, and test strategy for a pickup-points-modal feature.
+type: skill
+---
+
+# speckit-plan
+
+Use after `speckit-specify` has produced an approved `spec.md`. This
+skill breaks the spec into an **executable technical plan**, without
+implementing anything yet.
+
+## When to use
+
+- `specs/<slug>/spec.md` approved by the user.
+- The feature touches more than one file/layer (otherwise you can jump
+  straight to `speckit-tasks`).
+
+## Flow
+
+1. Read `specs/<slug>/spec.md`.
+2. Read [.specify/memory/constitution.md](../../../.specify/memory/constitution.md)
+   to check conflicts with binding principles.
+3. Run `.specify/scripts/bash/setup-plan.sh <slug>` if available.
+4. Fill `specs/<slug>/plan.md` using
+   [.specify/templates/plan-template.md](../../../.specify/templates/plan-template.md).
+
+## Expected output
+
+`specs/<slug>/plan.md` covering:
+
+- **Files to touch** (with rationale for each)
+- **Order of operations** (what comes first and why)
+- **Test strategy** (unit, integration, e2e if applicable)
+- **i18n plan** (new keys, locales touched)
+- **Risks** (backward-compat, performance, regression)
+- **Out of scope** explicitly stated
+
+## Constitution check
+
+Before marking the plan as ready, validate:
+
+- Principle 1 (backward-compat): does the change break the public
+  contract? Document it.
+- Principle 2 (tested behavior): does each behavioral change have a
+  planned test?
+- Principle 3 (i18n): is every new string listed?
+- Principle 4 (performance): added a synchronous request or bundle bloat?
+- Principle 5 (side-effect free): is the new utility pure?
diff --git a/.agents/skills/speckit-specify/SKILL.md b/.agents/skills/speckit-specify/SKILL.md
new file mode 100644
index 0000000..31e92c3
--- /dev/null
+++ b/.agents/skills/speckit-specify/SKILL.md
@@ -0,0 +1,44 @@
+---
+name: speckit-specify
+description: Generate a spec.md file under specs/<feature>/ describing a new pickup-points-modal feature in Business Context, Architectural Decisions, and Technical Contract sections.
+type: skill
+---
+
+# speckit-specify
+
+Use to turn a natural-language description into a structured `spec.md`.
+It is the first step of the Full Golden Path (SDD).
+
+## When to use
+
+- New feature requested via Jira/Slack.
+- The user says "spec this feature: ..." or "/speckit-specify ...".
+
+## Flow
+
+1. Create the `specs/<feature-slug>/` folder.
+2. Run `.specify/scripts/bash/create-new-feature.sh <slug>` if available;
+   otherwise create the folder manually.
+3. Fill `spec.md` using the template at
+   [.specify/templates/spec-template.md](../../../.specify/templates/spec-template.md).
+4. Mark unresolved fields as `TBD` — do not invent answers.
+5. Present the draft to the user before starting `speckit-plan`.
+
+## Minimum inputs to avoid mass-TBD
+
+- Who requested it (Jira/PM/stakeholder)?
+- What user-facing problem are we solving?
+- Which files/components are likely affected?
+
+## Output
+
+`specs/<slug>/spec.md` with the sections:
+- Business Context
+- Architectural Decisions
+- Technical Contract (props, fixtures, i18n, tests, acceptance)
+
+## Important
+
+`/specs` is in `.gitignore` — it is a local-only directory. Do not
+commit specs into this public repo. To archive, move them to the
+internal Confluence space.
diff --git a/.agents/skills/speckit-tasks/SKILL.md b/.agents/skills/speckit-tasks/SKILL.md
new file mode 100644
index 0000000..55282eb
--- /dev/null
+++ b/.agents/skills/speckit-tasks/SKILL.md
@@ -0,0 +1,43 @@
+---
+name: speckit-tasks
+description: Break an approved plan.md into a tasks.md list of small, sequenced, individually verifiable tasks for the pickup-points-modal feature implementation.
+type: skill
+---
+
+# speckit-tasks
+
+Turns an approved `plan.md` into a `tasks.md` of one-at-a-time
+executable items. It is the direct prerequisite for `speckit-implement`.
+
+## When to use
+
+- `specs/<slug>/plan.md` approved.
+- Ready to start coding.
+
+## Flow
+
+1. Read `specs/<slug>/plan.md`.
+2. Fill `specs/<slug>/tasks.md` with tasks that are:
+   - **Atomic:** one task = one concept changing (not "implement
+     everything").
+   - **Verifiable:** done when test X passes or behavior Y is
+     observable.
+   - **Ordered:** explicit dependencies (T2 depends on T1).
+3. Each task has: ID, title, files, done criteria, associated test.
+
+## Ideal size
+
+- 3–8 tasks for a small feature.
+- 8–15 tasks for a medium feature.
+- More than that, **break it into sub-features** — the plan is
+  probably too large.
+
+## Template
+
+See [.specify/templates/tasks-template.md](../../../.specify/templates/tasks-template.md).
+
+## Don't
+
+- Don't create an "implement everything" task.
+- Don't create a task without acceptance criteria.
+- Don't skip writing a test for a behavioral-change task (Principle 2).
diff --git a/.claude/commands b/.claude/commands
new file mode 120000
index 0000000..1ea3574
--- /dev/null
+++ b/.claude/commands
@@ -0,0 +1 @@
+../.agents/commands
\ No newline at end of file
diff --git a/.claude/rules b/.claude/rules
new file mode 120000
index 0000000..2d5c9a9
--- /dev/null
+++ b/.claude/rules
@@ -0,0 +1 @@
+../.agents/rules
\ No newline at end of file
diff --git a/.claude/skills b/.claude/skills
new file mode 120000
index 0000000..2b7a412
--- /dev/null
+++ b/.claude/skills
@@ -0,0 +1 @@
+../.agents/skills
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 7cd633b..235a10d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -29,4 +29,12 @@ yarn-debug.log*
 yarn-error.log*
 
 package-lock.json
-src/
\ No newline at end of file
+src/
+
+# SpecKit — commit spec.md; ignore ephemeral plan/tasks/analysis and local cache
+specs/**/plan.md
+specs/**/tasks.md
+specs/**/analysis.md
+.specify/cache/
+.specify/.tmp/
+.specify/feature.json
\ No newline at end of file
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
new file mode 100644
index 0000000..c1bcd16
--- /dev/null
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,120 @@
+# Pickup Points Modal — Project Constitution
+
+**Version** 1.0.0 | **Ratified** 2026-05-14 | **Last Amended** 2026-05-14
+
+This constitution defines the **binding** principles that govern technical
+and product decisions for `vtex.pickup-points-modal`. In case of conflict
+with any other source (README, CONTRIBUTING, external docs), this
+constitution prevails. Changes require a PR approved by 2 maintainers and
+a version bump in the **Governance** section below.
+
+## Principles
+
+### 1. Backward-compatible public API
+
+The contract exposed in [PickupPointsModal.js](../../react/PickupPointsModal.js)
+is consumed by production workspaces of stores using VTEX Checkout. Any
+change to props, events, or the shape of `orderForm`/`logisticsInfo`
+required by the component is **breaking** and demands a major bump in
+`manifest.json` (currently at `3.x`).
+
+- **Why:** VTEX IO apps and the NPM package `@vtex/pickup-points-modal`
+  receive this code via `1.x`/`3.x` dependency ranges; silently breaking
+  the contract takes down checkout in production stores.
+- **How to apply:** any PR touching `PickupPointsModal.js` requires a
+  dedicated review focused on the public contract plus an explicit
+  CHANGELOG entry.
+
+### 2. Tested behavior, not coverage number
+
+Behavioral changes require Jest tests that exercise the new behavior. The
+project does not target a fixed coverage percentage — what matters is
+that each shipped change has at least one test pinning the intended
+behavior.
+
+- **Why:** the codebase mixes legacy JS and TS, and VTEX's `orderForm`
+  has many optional fields. Coverage-by-number is misleading — bugs show
+  up in combinations that were not in the plan. Today's test suite is
+  intentionally narrow (~11 test files); this principle keeps the bar
+  on *new* behavior rather than retroactively asking for full coverage.
+- **How to apply:** PRs that change behavior without adding or updating
+  a test are pushed back to the author. Reproducing a production bug
+  with a failing test before the fix is the strongly preferred default,
+  not a hard gate.
+
+### 3. Internationalization is non-negotiable
+
+Every user-facing string goes through `react-intl`. New keys must be
+added to **all** locale files present in `messages/` in the same PR —
+even if the value is the original English string as a temporary
+fallback. `messages/context.json` is the English master and the source
+of truth for keys.
+
+The component currently ships with 31 locale files in `messages/`
+(plus `context.json` as the English master):
+
+```
+ar-SA  bg     ca     cs     da     de     el     en
+en-GB  en-LB  en-MM  en-US  es     fi     fr     id-ID
+it     ja     ko     nl     nn     no     pl     pt-BR
+pt-PT  ro     ru     sk     sl     sv     uk
+```
+
+- **Why:** the component runs across all the locales above in
+  production; missing a key in any one of them renders
+  `Missing translation` visibly in checkout.
+- **How to apply:** run `yarn lint:locales` (`intl-equalizer`) before
+  opening the PR. It must pass.
+
+### 4. Performance on the checkout-open path
+
+The modal opens in the critical purchase-completion flow. Changes must
+not:
+
+- Add unconditional network requests on initial render
+  (`componentDidMount`/`useEffect`) without cache or debounce.
+- Pull heavy libraries into the main bundle when a dynamic import or a
+  smaller alternative would do the job.
+- Break the existing gated load of Google Maps in
+  [`containers/withGoogleMaps.js`](../../react/containers/withGoogleMaps.js)
+  (the map only initializes when `googleMapsKey` is provided, via
+  `GoogleMapsContainer` from `vtex.address-form`).
+
+- **Why:** performance regressions on this path are visible to every
+  user who reaches the shipping step. There is no published numeric
+  budget — judgment is required, and PRs that grow bundle size or add
+  blocking work must justify the cost in the description.
+- **How to apply:** PRs that add a dependency must explain the size and
+  loading strategy in the description. Suspected regressions open a
+  profiling task before merge.
+
+### 5. Side-effect aware utilities
+
+Functions under `react/utils/` should be pure. Functions that perform
+I/O or telemetry must declare it in the name (`fetchX`, `saveY`, the
+`...Event` suffix used in [`utils/metrics.js`](../../react/utils/metrics.js)).
+Network calls live under `react/fetchers/`.
+
+- **Why:** this makes it easy to unit-test utilities without mounting
+  the full component tree with providers.
+- **How to apply:** PRs that add global state to a utility (a singleton,
+  a mutable module-level cache) go back to the author with a suggestion
+  to move it into `containers/` or `ModalState.js`.
+- **Known exception:** `react/fetchers/index.js` installs a global
+  `axios-retry` interceptor at module load. Any new module-level
+  mutation of shared singletons must be reviewed against this
+  precedent and added here.
+
+## Governance
+
+- **Ratified by:** repo maintainers + Checkout team tech lead.
+- **How to propose a change:** PR editing this file, linked to a short
+  RFC in the description. Minimum 2 approvals required.
+- **Versioning:** follow SemVer in the `Version` field above. Patch for
+  clarification, minor for a new principle, major for revoking or
+  rewriting an existing principle.
+- **Audit:** full constitution review every 6 months, or whenever a
+  principle is violated in production (incident review).
+- **Conflicts with AGENTS.md:** the constitution wins. AGENTS.md
+  describes the "how"; the constitution describes the "why" and "what
+  not to do".
diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh
new file mode 100755
index 0000000..cfff8da
--- /dev/null
+++ b/.specify/scripts/bash/check-prerequisites.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# check-prerequisites.sh
+# Verifies that the SpecKit + Cowork setup in this repo is consistent.
+# Exits non-zero and lists what is missing.
+
+set -euo pipefail
+. "$(dirname "$0")/common.sh"
+
+root="$(repo_root)"
+errors=0
+
+check() {
+  local description="$1"
+  local condition="$2"
+  if eval "$condition" >/dev/null 2>&1; then
+    printf "  ✓ %s\n" "$description"
+  else
+    printf "  ✗ %s\n" "$description"
+    errors=$((errors + 1))
+  fi
+}
+
+printf "AI artifacts:\n"
+check "AGENTS.md exists"                       "[ -f \"$root/AGENTS.md\" ]"
+check "CLAUDE.md is a symlink to AGENTS.md"    "[ \"\$(readlink \"$root/CLAUDE.md\" 2>/dev/null)\" = \"AGENTS.md\" ]"
+check ".agents/skills/ exists"                 "[ -d \"$root/.agents/skills\" ]"
+check ".agents/commands/ exists"               "[ -d \"$root/.agents/commands\" ]"
+check ".agents/rules/ exists"                  "[ -d \"$root/.agents/rules\" ]"
+
+printf "\nSDD Lite:\n"
+check "skill 'specification' present"          "[ -f \"$root/.agents/skills/specification/SKILL.md\" ]"
+check "skill 'implementing' present"           "[ -f \"$root/.agents/skills/implementing/SKILL.md\" ]"
+
+printf "\nSDD Full:\n"
+check "constitution.md present"                "[ -f \"$root/.specify/memory/constitution.md\" ]"
+check "templates (>=5)"                        "[ \$(ls $root/.specify/templates/*-template.md 2>/dev/null | wc -l) -ge 5 ]"
+check "scripts/bash (>=5)"                     "[ \$(ls $root/.specify/scripts/bash/*.sh 2>/dev/null | wc -l) -ge 5 ]"
+
+printf "\nGitignore:\n"
+check "/specs ignored"                         "grep -q '^/specs$' \"$root/.gitignore\""
+check ".specify/feature.json ignored"          "grep -qE '^\\.specify/feature\\.json$' \"$root/.gitignore\""
+
+if [ "$errors" -gt 0 ]; then
+  printf "\n%d check(s) failed\n" "$errors"
+  exit 1
+fi
+
+printf "\nall checks passed ✓\n"
diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh
new file mode 100755
index 0000000..3830390
--- /dev/null
+++ b/.specify/scripts/bash/common.sh
@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# common.sh — shared helpers for SpecKit scripts.
+# Source from sibling scripts:  . "$(dirname "$0")/common.sh"
+
+set -euo pipefail
+
+# Absolute path to the repo root (works even if the script is invoked
+# from a different CWD).
+repo_root() {
+  git rev-parse --show-toplevel
+}
+
+# Directory where local-only specs live (git-ignored).
+specs_dir() {
+  printf "%s/specs" "$(repo_root)"
+}
+
+# SpecKit state directory.
+specify_dir() {
+  printf "%s/.specify" "$(repo_root)"
+}
+
+# Slugify a title: "Add awesome feature!" -> "add-awesome-feature".
+slugify() {
+  printf "%s" "$1" \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+|-+$//g'
+}
+
+# Print to stderr and exit non-zero.
+die() {
+  printf "error: %s\n" "$*" >&2
+  exit 1
+}
+
+# Fail loudly if the working tree has pending changes.
+require_clean_tree() {
+  if ! git diff --quiet || ! git diff --cached --quiet; then
+    die "working tree is not clean — commit or stash before running"
+  fi
+}
+
+# Assert that a file exists; abort otherwise.
+require_file() {
+  [ -f "$1" ] || die "required file missing: $1"
+}
diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh
new file mode 100755
index 0000000..5b36b6d
--- /dev/null
+++ b/.specify/scripts/bash/create-new-feature.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# create-new-feature.sh <slug-or-title>
+# Creates the specs/<slug>/ structure with a fresh spec.md from the template.
+
+set -euo pipefail
+. "$(dirname "$0")/common.sh"
+
+[ $# -ge 1 ] || die "usage: $(basename "$0") <slug-or-title>"
+
+slug="$(slugify "$1")"
+[ -n "$slug" ] || die "invalid slug"
+
+root="$(repo_root)"
+target="$root/specs/$slug"
+
+if [ -d "$target" ]; then
+  die "feature already exists: specs/$slug"
+fi
+
+mkdir -p "$target"
+cp "$root/.specify/templates/spec-template.md" "$target/spec.md"
+
+# Track the active feature in .specify/feature.json (git-ignored).
+mkdir -p "$root/.specify"
+printf '{"slug":"%s","created":"%s"}\n' "$slug" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  > "$root/.specify/feature.json"
+
+printf "created: specs/%s/spec.md\n" "$slug"
+printf "active feature: %s\n" "$slug"
diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh
new file mode 100755
index 0000000..19ec324
--- /dev/null
+++ b/.specify/scripts/bash/setup-plan.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# setup-plan.sh [slug]
+# Generates plan.md from the template for the active feature (or the slug
+# passed as an argument).
+
+set -euo pipefail
+. "$(dirname "$0")/common.sh"
+
+root="$(repo_root)"
+
+if [ $# -ge 1 ]; then
+  slug="$(slugify "$1")"
+else
+  feature_file="$root/.specify/feature.json"
+  require_file "$feature_file"
+  slug=$(sed -n 's/.*"slug":"\([^"]*\)".*/\1/p' "$feature_file")
+  [ -n "$slug" ] || die "could not determine the active feature"
+fi
+
+target="$root/specs/$slug"
+[ -d "$target" ] || die "specs/$slug does not exist — run create-new-feature.sh first"
+require_file "$target/spec.md"
+
+if [ -f "$target/plan.md" ]; then
+  die "specs/$slug/plan.md already exists"
+fi
+
+cp "$root/.specify/templates/plan-template.md" "$target/plan.md"
+printf "created: specs/%s/plan.md\n" "$slug"
diff --git a/.specify/scripts/bash/setup-tasks.sh b/.specify/scripts/bash/setup-tasks.sh
new file mode 100755
index 0000000..bfbe151
--- /dev/null
+++ b/.specify/scripts/bash/setup-tasks.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# setup-tasks.sh [slug]
+# Generates tasks.md from the template for the active feature (or the slug
+# passed as an argument).
+
+set -euo pipefail
+. "$(dirname "$0")/common.sh"
+
+root="$(repo_root)"
+
+if [ $# -ge 1 ]; then
+  slug="$(slugify "$1")"
+else
+  feature_file="$root/.specify/feature.json"
+  require_file "$feature_file"
+  slug=$(sed -n 's/.*"slug":"\([^"]*\)".*/\1/p' "$feature_file")
+  [ -n "$slug" ] || die "could not determine the active feature"
+fi
+
+target="$root/specs/$slug"
+[ -d "$target" ] || die "specs/$slug does not exist"
+require_file "$target/plan.md"
+
+if [ -f "$target/tasks.md" ]; then
+  die "specs/$slug/tasks.md already exists"
+fi
+
+cp "$root/.specify/templates/tasks-template.md" "$target/tasks.md"
+printf "created: specs/%s/tasks.md\n" "$slug"
diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
new file mode 100755
index 0000000..b4dbaa4
--- /dev/null
+++ b/.specify/scripts/bash/update-agent-context.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# update-agent-context.sh
+# Prints a context summary on stdout — useful to paste into an agent prompt.
+# Reads AGENTS.md, constitution.md and the active feature (if any).
+
+set -euo pipefail
+. "$(dirname "$0")/common.sh"
+
+root="$(repo_root)"
+
+printf "# Agent context (auto-generated)\n\n"
+printf "## Repo\n"
+printf "- %s (branch: %s)\n" "$(basename "$root")" "$(git rev-parse --abbrev-ref HEAD)"
+printf "- last commit: %s\n\n" "$(git log -1 --pretty=%h\ %s)"
+
+if [ -f "$root/AGENTS.md" ]; then
+  printf "## AGENTS.md headers\n"
+  grep -E '^## ' "$root/AGENTS.md" | sed 's/^## /- /'
+  printf "\n"
+fi
+
+if [ -f "$root/.specify/memory/constitution.md" ]; then
+  printf "## Constitution principles\n"
+  grep -E '^### ' "$root/.specify/memory/constitution.md" | sed 's/^### /- /'
+  printf "\n"
+fi
+
+feature_file="$root/.specify/feature.json"
+if [ -f "$feature_file" ]; then
+  slug=$(sed -n 's/.*"slug":"\([^"]*\)".*/\1/p' "$feature_file")
+  printf "## Active feature\n"
+  printf "- slug: %s\n" "$slug"
+  [ -f "$root/specs/$slug/spec.md" ]  && printf "- spec.md: present\n"
+  [ -f "$root/specs/$slug/plan.md" ]  && printf "- plan.md: present\n"
+  [ -f "$root/specs/$slug/tasks.md" ] && printf "- tasks.md: present\n"
+fi
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6da540c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,103 @@
+# AGENTS.md — pickup-points-modal
+
+Canonical onboarding for AI agents and new engineers working in this
+repository. This file is the **operational source of truth** — read it
+before touching any file.
+
+- **App:** `vtex.pickup-points-modal` (VTEX IO React component)
+- **Stack:** React + TypeScript + legacy JavaScript, VTEX IO React builder, Jest
+- **VTEX IO layout:** `react/` (no `node/`)
+- **Lifecycle:** `stable` (production checkout component)
+
+## Golden Path mode
+
+- **Default flow:** `Full` (SDD Lite + SDD Full enabled)
+- **Rationale:** critical checkout component — new features must go through
+  spec + plan + tasks before any implementation work.
+- **Lite-only is allowed** for hotfixes on `fix/*` or `chk-*` branches.
+
+## Sources of truth
+
+Order matters: items higher in the list override the ones below in case of
+conflict.
+
+- [.specify/memory/constitution.md](.specify/memory/constitution.md) — binding
+  principles (testing, performance, i18n). The project constitution.
+- [README.md](README.md) — public API and `PickupPointsModal` props.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — PR flow and changelog rules.
+- [manifest.json](manifest.json) — published version and VTEX IO dependencies.
+- [react/PickupPointsModal.js](react/PickupPointsModal.js) — root component.
+- [VTEX IO docs](https://developers.vtex.com/docs/guides/vtex-io-documentation) —
+  builders, runtime and publish flow.
+- **Product artifacts (L3) — public repo:** this repository is public on
+  GitHub; product vision / one-pager / PRDs must live in an internal
+  private companion repo or doc space, **not** in this repo. Companion
+  location: `<companion-private-repo TBD>` — to be filled in by the
+  Checkout team. Until set, any product decision driving a PR must be
+  linked in the PR description.
+
+## Verified commands
+
+All commands below have been verified as executable from the repo root.
+**Always run `yarn install` before the first execution.**
+
+- `yarn install` — install dependencies (root + `react/`).
+- `yarn lint` — run ESLint over `js,jsx,ts,tsx`.
+- `yarn lint-fix` — ESLint with `--fix`.
+- `yarn lint:ts` — typecheck via `tsc --noEmit -p react/tsconfig.json`.
+- `yarn lint:locales` — `intl-equalizer` over `messages/` (i18n).
+- `yarn test` — Jest on the `react/` workspace.
+- `yarn test:coverage` — Jest with coverage.
+- `yarn test:watch` — Jest in watch mode.
+- `yarn build` — production build (`lib/` + locales).
+- `yarn start` — `nwb serve-react-demo` (local dev server).
+- `yarn format` — Prettier over `**/*.{ts,tsx,js,jsx,json}`.
+
+## Expected skills
+
+Skills available under [.agents/skills/](.agents/skills/). The agent must
+invoke the appropriate skill before starting feature work.
+
+| Skill | When to use |
+|---|---|
+| `specification` | Create an SDD doc (Business Context + Arch + Technical Contract) before a new feature. |
+| `implementing` | Implement an approved spec autonomously up to the PR. |
+| `speckit-constitution` | Edit/create the project constitution. |
+| `speckit-specify` | Generate a `spec.md` from a feature description. |
+| `speckit-plan` | Break a spec into a technical plan (`plan.md`). |
+| `speckit-tasks` | Break a plan into executable tasks (`tasks.md`). |
+| `speckit-implement` | Execute the generated tasks in code. |
+| `speckit-analyze` | Audit consistency between spec/plan/tasks/code. |
+| `speckit-clarify` | Clarify ambiguous requirements before planning. |
+| `speckit-checklist` | Generate per-feature validation checklist. |
+| `speckit-git-feature` | Create a feature branch following the repo convention. |
+| `speckit-git-commit` | Compose Conventional Commits + Changeset entries. |
+
+## Autonomy limits
+
+The agent **may** freely modify, without confirmation:
+
+- Files under `react/components/`, `react/containers/`, `react/utils/`,
+  `react/fetchers/`, `react/types/`.
+- Tests under `react/**/__tests__/` and `react/**/*.test.{js,ts,tsx}`.
+- Messages under `messages/` as long as `messages/context.json` stays in
+  English and new keys are added across all locales.
+
+The agent **must ask for confirmation** before:
+
+- Changing `manifest.json` (especially `version`, `dependencies`, `builders`).
+- Changing `package.json` (dependencies, scripts, engines).
+- Changing `.vtex/deployment.yaml`, `.travis.yml`, `.github/`, or any
+  CI/CD pipeline.
+- Changing `react/PickupPointsModal.js` or `react/ModalState.js` (root
+  components).
+- Publishing/release: `vtex publish`, `npm publish`, or bumping
+  `CHANGELOG.md`.
+
+The agent **must never**:
+
+- Run `vtex publish`, `npm publish`, or `git push --force` on `main`.
+- Skip hooks (`--no-verify`) or disable SonarQube/lint to unblock a PR.
+- Commit secrets, tokens, `.env*` files, or Google Maps keys.
+- Mock the `orderForm` in integration tests — use the fixtures under
+  `react/__mocks__/`.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 0000000..47dc3e3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file