diff --git a/.specify/SPEC_template.md b/.specify/SPEC_template.md
new file mode 100644
index 000000000..ddd124f0a
--- /dev/null
+++ b/.specify/SPEC_template.md
@@ -0,0 +1,79 @@
+# Feature Spec: [FEAT-XXX] - Short Descriptive Title
+
+**Milestone:** [e.g. MVP Core / Performance & Polish / Extension Framework]
+**Priority:** Must-have / Should-have / Nice-to-have
+**Spec Owner:** [Your Name / AI Agent Name]
+**Status:** Draft → Under Review → Approved → Implemented → Verified
+
+## 1. Purpose & User Story
+
+As a [user type], I want [goal] so that [benefit].
+
+_(One clear sentence. Keep it concise.)_
+
+## 2. Functional Requirements
+
+- [ ] REQ-1: [Clear, testable description]
+- [ ] REQ-2: ...
+- [ ] REQ-3: ...
+
+_(List what the feature must do. Make each item verifiable.)_
+
+## 3. Non-Functional Requirements
+
+- **Performance:** [e.g. Latency < 800ms at p95, max 5k tokens, etc.]
+- **Security / Safety:** [e.g. Input validation, no raw errors to user, etc.]
+- **Compatibility:** [e.g. Works with all existing wallet backends, no breaking changes for extensions]
+- **UI/UX:** [e.g. Follows existing Quasar/Vue patterns in wallet.js]
+- **Other:** [cost, scalability, accessibility, etc.]
+
+## 4. Technical Approach (Optional – recommended for complex features)
+
+- Proposed solution: [e.g. Extend existing CRUD in lnbits/core/, new extension, middleware change, etc.]
+- Key files to modify: [list expected files]
+- New dependencies: [none / specific package + version]
+- Migration / Database changes: [yes/no + description]
+
+## 5. Success Criteria & Verification
+
+**Must pass all of these to be accepted:**
+
+- [ ] All functional requirements (REQ-\*) implemented and tested
+- [ ] Non-functional requirements met (performance, security, etc.)
+- [ ] Relevant tests pass: `make test-unit`, `make test-api`, `make test-regtest` (as applicable)
+- [ ] `make check` passes (ruff, mypy, pyright, prettier, checkbundle)
+- [ ] Constitution compliance: All changes respect CONSTITUTION.md
+- [ ] Backward compatibility: No breakage for existing extensions or wallet backends
+- [ ] Documentation updated (if applicable: README, OpenAPI, inline comments)
+
+**Additional Tests / Edge Cases:**
+
+- [ ] Test invalid inputs / error paths
+- [ ] Test with FakeWallet and at least one real backend
+- [ ] Test with multiple extensions installed
+
+## 6. Safety & Risk Assessment
+
+- Potential risks: [e.g. Payment flow impact, key exposure, extension conflicts]
+- Mitigation: [how addressed]
+- Security review needed: [yes/no]
+
+## 7. Implementation Notes (for AI / Developer)
+
+- Style to match: Existing code patterns in `lnbits/core/` and `wallet.js`
+- Surgical changes only (per AGENTS.md)
+- Any known gotchas or dependencies on other features:
+
+## 8. Acceptance Checklist (Sign-off)
+
+- [ ] Spec reviewed and approved by project owner
+- [ ] Implementation completed
+- [ ] Verification steps passed
+- [ ] PR created with link to this spec
+- [ ] Constitution & AGENTS.md compliance confirmed
+
+---
+
+**Created:** [Date]
+**Last Updated:** [Date]
+**Approved By:** [Name / "Approved"]
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..6e68b3379
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,122 @@
+# AGENTS.md - Instructions for All AI Coding Agents
+
+This file is the **master instruction manual** for any AI agent (Grok, Claude, Cursor, Aider, etc.) working on LNbits.
+
+## 1. Core Rule (Never Break This)
+
+**You MUST read and strictly follow `CONSTITUTION.md` before doing any planning, coding, refactoring, or suggesting changes.**
+
+- Every single change, feature, extension, or fix **must comply** with the Constitution.
+- If you detect a violation (in new code or existing code), you **must** flag it immediately and propose a fix or ask for clarification.
+- Constitution > any other instruction (including this file, user prompts, or previous conversations).
+
+## 2. Mandatory Development Workflow
+
+For **any non-trivial task** (new feature, bug fix, refactor, extension change):
+
+1. **Constitution Check** – Re-read relevant sections of `CONSTITUTION.md`
+2. **Feature Spec Check** – If a spec exists in `.specify/`, follow it exactly. If none exists, ask the user for clarification or propose a minimal spec.
+3. **Think Step-by-Step** – Follow the "Think Before Coding" and "Simplicity First" guidelines below.
+4. **Surgical Changes** – Only touch what is necessary.
+5. **Implement**
+6. **Verify** – Run relevant tests (`make test-unit`, `make test-api`, etc.), `make check`, and confirm compliance.
+7. **Report** – Always include a clear summary.
+
+Use the following response format:
+
+```markdown
+## Constitution & Spec Compliance
+
+- Relevant Constitution sections checked: [list or quote key rules]
+- Feature Spec followed: [yes / no / proposed]
+
+## Assumptions & Plan
+
+- Assumptions: ...
+- Plan:
+  1. ...
+  2. ...
+- Tradeoffs considered: ...
+
+## Changes Made
+
+- Files changed: ...
+- Summary of modifications:
+
+## Verification
+
+- [ ] Passes `make check`
+- [ ] Relevant tests pass (`make test-xxx`)
+- [ ] Complies with Constitution
+- [ ] Surgical & minimal (no unrelated changes)
+```
+
+## 3. Behavioral Guidelines (Merged & Project-Specific)
+
+**Think Before Coding**
+
+- Don't assume. Don't hide confusion. Surface tradeoffs.
+- State assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If something is unclear (especially regarding wallets, extensions, or funding sources), stop and ask.
+
+**Simplicity First**
+
+- Minimum code that solves the problem. Nothing speculative.
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- Respect LNbits' lean core philosophy: new functionality should preferably go into an **extension** unless it truly belongs in core.
+
+**Surgical Changes**
+
+- Touch only what you must. Clean up only your own mess.
+- Match existing style (Python: Black + Ruff rules; JS: Prettier).
+- Do not "improve" or refactor adjacent code unless explicitly asked.
+- When editing, remove only imports/variables/functions made unused **by your changes**.
+- Never delete pre-existing dead code unless instructed.
+
+**Goal-Driven Execution**
+
+- Transform tasks into verifiable goals.
+- For tests: Write or update tests first when fixing bugs or adding behavior.
+- Always consider impact on existing extensions and multiple wallet backends (LND, CLN, Boltz, VoidWallet, etc.).
+
+## 4. LNbits-Specific Rules
+
+- **Extensions First**: Core should remain lean. Prefer implementing new features as extensions unless they are fundamental to wallets, security, or the API.
+- **Testing**: Use `FakeWallet` for unit/API tests. Regtest tests for full Lightning flows. Never break existing test targets in the Makefile.
+- **Dependencies**: Never add new dependencies without updating `pyproject.toml` and getting approval.
+- **Frontend**: JS/Vue code (e.g. `wallet.js`) must follow existing patterns and pass `make checkbundle` when static files are affected.
+- **Database / Migrations**: Do not make raw SQL changes. Use existing CRUD/services and migration tooling.
+- **Security**: Be extremely cautious with anything touching payments, keys, LNURL, Bolt11, or admin routes.
+- **Tools**: Use `uv run` for all commands. Prefer Makefile targets (`make format`, `make check`, `make test-xxx`).
+- **Generated Files**: Never modify gRPC files or other generated code.
+
+## 5. Forbidden Behaviors
+
+- Ignoring Constitution rules to "be helpful"
+- Large refactors without a spec or explicit request
+- Adding features "for future use"
+- Breaking backward compatibility for extensions or existing wallet backends
+- Committing code that fails `make check` or relevant tests
+- Exposing raw errors/stack traces to users
+- Using synchronous code in hot async paths without justification
+
+## 6. How to Handle This File + Constitution
+
+When the user gives you a task, start your response with:
+
+> Following LNbits CONSTITUTION.md and AGENTS.md...
+
+Then proceed with the structured format above.
+
+---
+
+**These guidelines are working if:**
+
+- Fewer unnecessary changes appear in diffs
+- Clarifying questions come **before** implementation
+- All changes respect the lean, extension-first, security-first nature of LNbits
+- Tests and `make check` continue to pass
+
+Last Updated: April 2026
diff --git a/CONSTITUTION.md b/CONSTITUTION.md
new file mode 100644
index 000000000..53d62e021
--- /dev/null
+++ b/CONSTITUTION.md
@@ -0,0 +1,136 @@
+# CONSTITUTION.md
+
+This is the immutable constitution of the LNbits project.
+Every feature spec, code change, refactor, extension, or decision by humans or AI agents **must comply** with this document.
+Changes to this file require explicit approval from the project owner/maintainers.
+
+## 1. Project Overview
+
+**Project Name:** LNbits
+**Core Purpose:** Free and open-source Lightning wallet and accounts system. A lightweight Python server that sits on top of any Lightning funding source, providing safe isolated wallets, a clean REST API, and a powerful extension system for adding features rapidly.
+**Target Users:** Individuals, communities, merchants, developers, and enterprises building on Bitcoin/Lightning (self-hosted or as part of larger stacks).
+**High-Level Success Criteria:**
+
+- Reliable multi-wallet Lightning accounting with any backend (20+ supported funding sources)
+- Secure, extensible via 60+ extensions without bloating core
+- High code quality, test coverage, and backward compatibility for extensions
+- Production-ready performance and security for real Bitcoin value
+
+**Version:** 1.5.4
+
+## 2. Technology Stack (Strict)
+
+- **Language:** Python >=3.10, <3.13 (strictly enforced via `pyproject.toml`)
+- **Framework:** FastAPI + Starlette (backend API)
+- **Frontend:** Vue.js + Quasar framework, with bundled static assets
+- **Database:** SQLite (aiosqlite) by default, PostgreSQL (asyncpg/psycopg2) supported via `LNBITS_DATABASE_URL`
+- **Async Runtime:** uvloop preferred
+- **Dependency Management:** uv + pyproject.toml (Hatchling build backend). Use `uv run` for all commands.
+- **Wallet Backends:** Abstracted via `lnbits.wallets` – support for LND, Core Lightning, Phoenixd, Boltz, Breez SDK, Liquid, VoidWallet fallback, etc. New backends must follow existing abstraction.
+- **Other Key Libs:** SQLAlchemy, Pydantic (v1), Loguru, Jinja2, LNURL, Bolt11, etc. (see `pyproject.toml` for pinned versions)
+- **Build/Frontend Tools:** npm for bundling (Quasar/Vue), Prettier for JS/CSS (check Makefile targets)
+
+**Forbidden:**
+
+- Adding new top-level dependencies without updating `pyproject.toml` **and** team approval
+- Using synchronous blocking calls in async paths (except where explicitly justified)
+- Direct database queries outside of CRUD layers or core services
+- Modifying generated files (e.g., gRPC files in wallets/boltz_grpc_files or lnd_grpc_files)
+
+## 3. Architecture & Code Organization (Mandatory Rules)
+
+- **Core Principle:** Modular monolith with heavy emphasis on **extensions**. All non-core features must live in extensions (installed via `lnbits/extensions`). Core stays lean.
+- **Backend Structure:**
+  - `lnbits/core/` for core models, CRUD, services, routers, tasks
+  - `lnbits/wallets/` for funding source abstractions
+  - `lnbits/extensions/` for installed/upgradeable extensions (do not commit large extensions to core repo)
+  - `lnbits/static/` for bundled frontend assets (managed via npm bundle)
+- **Key Rules:**
+  - Use dependency injection and FastAPI routers properly
+  - Extensions register routes/tasks via `register_ext_routes` / `register_ext_tasks`
+  - Database migrations handled centrally (extension-specific migrations)
+  - All new endpoints must be under proper versioning/prefixing where applicable
+  - Frontend: Vue 2/Quasar components in `wallet.js` style (or updated) – keep reactive, use LNbits.utils helpers
+  - No circular imports; respect existing middleware order (e.g., InstalledExtensionMiddleware before ExtensionsRedirectMiddleware)
+
+**Exclusions** (do not lint/format these):
+
+- `lnbits/extensions/`, `lnbits/upgrades/`, generated gRPC files, static/vendor bundles
+
+## 4. Code Quality & Style
+
+- **Formatting & Linting:**
+  - Python: Black (line-length 88), Ruff (with selected rules: F, E, W, I, A, C, N, UP, RUF, B, S), MyPy (strict where possible), Pyright
+  - JS/Frontend: Prettier
+  - Run via Makefile: `make format` and `make check`
+- **Type Checking:** MyPy + Pyright enforced on `lnbits/`, `tests/`, `tools/`
+- **Testing Requirements:**
+  - Unit, API, wallet, and regtest tests via pytest (see Makefile targets)
+  - New core code or critical paths: high coverage expected (`--cov=lnbits`)
+  - Extensions should include their own tests where possible
+- **Error Handling & Logging:** Use Loguru with structured context. Never expose raw stack traces to end users. Graceful fallbacks (e.g., VoidWallet on funding source failure).
+- **Pre-commit:** Strongly recommended (`make install-pre-commit-hook`)
+- **Bundle Integrity:** Frontend bundles must pass `make checkbundle` before commits affecting static files.
+
+## 5. AI / LLM Usage Standards (if any agents or future AI features are added)
+
+- Any new AI-powered features (e.g., via extensions) must use structured outputs (Pydantic/JSON mode)
+- Store prompts/templates versioned in the extension
+- Prefer deterministic behavior for financial/security paths (low temperature)
+- All AI outputs involving value/money must be validated server-side
+- Safety: Never allow untrusted model output to influence payments, wallet balances, or admin actions without guardrails
+
+## 6. Safety, Security & Ethics
+
+- **Critical:** Handle real Bitcoin/Lightning value → security-first mindset
+- Per-wallet isolation with separate admin/invoice/read keys
+- Rate limiting (SlowAPI) and IP blocking middleware mandatory
+- Sanitize all user inputs; validate LNURL, Bolt11, etc.
+- PII: Minimal collection; respect privacy (no unnecessary logging of sensitive data)
+- Funding source failures: Graceful degradation to VoidWallet + clear logging
+- Extensions: Hash-verified installs for vetted extensions; careful with custom extension paths
+- Audit logging via AuditMiddleware
+- Forbidden: Hard-coded secrets, insecure subprocess calls without review, SQL injection risks (use SQLAlchemy properly)
+
+## 7. Performance & Cost Budgets
+
+- Keep core lightweight – extensions handle heavy features
+- Async-first (uvloop, asyncpg/aiosqlite)
+- Reasonable retry logic for funding source connections (see `check_funding_source`)
+- Frontend: Optimized bundles (checkbundle enforced)
+- No unnecessary blocking operations in request paths
+
+## 8. Development Workflow (Spec-Driven where possible)
+
+- **All significant changes** should follow Spec-Driven Development:
+  - Create/update Feature Spec in `.specify/` folder (or equivalent)
+  - Reference this Constitution in every spec and PR
+- Use Makefile targets for format/check/test
+- Tests run with `FakeWallet` by default for unit/API; regtest for full flows
+- PRs must:
+  - Pass `make check` and relevant tests
+  - Include Constitution compliance notes (via AGENTS.md/CLAUDE.md)
+  - Not break existing extensions or wallet backends
+- Branching: Protect main; use feature branches
+- Extensions: Develop separately; core repo focuses on framework stability
+
+## 9. Decision Hierarchy (What Takes Precedence)
+
+1. This Constitution
+2. Approved Feature Spec / Milestone
+3. Existing tests and backward compatibility (especially for extensions and wallet backends)
+4. Project maintainers / owner decision
+5. Everything else (including helpful AI suggestions)
+
+If conflict: Stop, document the issue, and seek clarification from maintainers.
+
+## 10. Amendment Process
+
+- This Constitution can only be changed with explicit approval from project maintainers.
+- All changes must be dated, versioned, and reflected in `AGENTS.md`.
+- Minor clarifications can be proposed via PR with justification.
+
+---
+
+**Last Updated:** April 2026 (based on v1.5.4)
+**Owner/Maintainers Approval:** LNbits Team