License: CC BY 4.0 (Creative Commons Attribution 4.0 International) Copyright: © 2026 Hypercart DBA Neochrome, Inc. Attribution Required: When sharing or adapting this work, you must:

• Credit "Hypercart DBA Neochrome, Inc." as the original author
• Provide a link to https://creativecommons.org/licenses/by/4.0/
• Indicate if changes were made
• Not remove this attribution notice

License Terms: https://creativecommons.org/licenses/by/4.0/legalcode

• Use UnifiedLayout + UnifiedSidebar for all pages; do not reintroduce deprecated layout patterns.
• Define page max-width once in UnifiedLayout.tsx; never add per-page width overrides.
• Use useAuthStore() as auth source of truth; no hardcoded user/org IDs.
• Use useCmsConfig + src/services/cms-config.ts for CMS; no direct page-level Supabase calls.
• Implement RLS (including tenant isolation rules) before shipping user-facing features.
• Log intentional architectural violations in CHANGELOG.md with #lessonslearned.

• Treat each section as a pass/fail checklist.
• Mark items done only with code evidence (files, tests, policies, or logs).
• Follow the order: pre-build → build contract → post-build → continuous loop.
• First time in this repo? Extract the DASHBOARD.md and QUICKHELP.md templates (see Section 0.0 below).
• Need quick help? Start with QUICKHELP.md.
• Checking compliance status? See DASHBOARD.md.
• New build cycle? Reset the dashboard checkboxes and update dates in DASHBOARD.md.

AI Agent Instruction: On first use in a new repo, check whether DASHBOARD.md and QUICKHELP.md exist in the project root. If they do not exist, extract them from the templates in Appendix A and Appendix B below. After extraction:

1. Create DASHBOARD.md from the Appendix A template.
2. Create QUICKHELP.md from the Appendix B template.
3. Confirm both files exist before proceeding with any build work.

If both files already exist, skip this step.

The compliance matrix tracks pass/fail status for each architecture section across build, QA, and manual testing phases. It is maintained as a living dashboard in a dedicated file.

→ DASHBOARD.md — Compliance Matrix

• Make one change cluster at a time, verify it, then proceed.
• Edit surgically; do not delete or rewrite files wholesale unless explicitly requested.
• Check existing code before creating new files, hooks, or services.
• If a pattern is unclear, ask: "Which AGENTS.md pattern applies here?"
• Prefer smallest working diff that preserves current contracts.

• Before creating a new utility/helper, search existing implementations in src/services/, src/lib/, and src/utils/.
• Keep dependency direction one-way: pages/components -> hooks/services -> integrations.
• Avoid circular imports and cross-feature back-references.
• Reuse public module exports before adding parallel helpers.
• Keep one canonical helper per concern to prevent drift.

• Capture the failing command and first actionable error.
• Isolate the latest change that introduced failure.
• Fix the smallest root cause first (types/imports/contracts before refactors).
• Re-run the failing command, then rerun the full verification set.
• If unresolved, revert only your latest change chunk and retry with a narrower diff.

The architecture snapshot captures the current state of layout, CMS, state management, security, and observability decisions. It is updated after each release.

→ DASHBOARD.md — Architecture Snapshot

The Overall Health Grade is a high-level indicator of the project's architectural health and compliance, derived from the completed compliance matrix in DASHBOARD.md. It provides an at-a-glance summary of the build cycle's quality.

• Grade A: Fully compliant; all checklist items passed.
• Grade B: Minor, non-critical deviations; requires review.
• Grade C: One or more significant deviations; requires immediate fixes.
• Grade D/F: Multiple critical violations; build is at risk.

The grade is assessed at the end of each audit cycle and serves as a guide for prioritization. A grade of B- or below signals that technical debt remediation should be prioritized over new features.

• Define domain boundaries: auth, monitoring/events, admin CMS, shared UI, tenant isolation.
• Define tenant model: single-tenant vs. multi-tenant, user-level vs. org-level isolation, shared vs. tenant-scoped tables.
• Define source of truth: Supabase for persisted data, Zustand for shared client state, component state for local ephemeral UI.
• Freeze folder contracts: src/pages, src/components, src/stores, src/integrations/supabase.
• Design app_config keys and RLS before building CMS-driven pages.
• Design RLS policies for tenant data tables before building user-facing features.
• Define typed contracts first (query result types, union states, service interfaces).

• All pages use UnifiedLayout from src/components/layouts/.
• UnifiedSidebar.tsx remains the single sidebar for all auth states.
• UnifiedSidebar nav states remain:
  • logged out: Home, Status, Changelog, Terms (/tos), Sign-up, Sign-in
  • logged in user: Dashboard, Monitors, Profile, Status, Changelog, Terms, Sign out
  • logged in admin: Dashboard, Monitors, Profile, Admin, Status, Changelog, Terms, Sign out
• Footer remains embedded in UnifiedSidebar.tsx.
• Standalone <Footer /> is not rendered in pages.
• Do not reintroduce deprecated patterns: PublicNavbar.tsx, custom per-page wrappers, standalone page footers.
• Page/container max-width is defined once in UnifiedLayout.tsx; individual pages must not redeclare or override container widths.
• Do not add per-page max-w-*, w-*, or inline width styles that duplicate or conflict with the layout-level max-width setting.

• CMS values are JSON strings in app_config table.
• Keys remain: tos_html (Terms content), footer_html (Footer content).
• All CMS reads/writes go through src/services/cms-config.ts service layer (DRY + SRP).
• Service exposes typed interface: getConfig(key), setConfig(key, value) (admin-only).
• Service handles JSON parse/stringify internally; consumers receive typed data.
• Components/pages use useCmsConfig(key) hook, never direct Supabase calls (Dependency Inversion).
• Hook returns { data, loading, error } with proper async state modeling (see Section 5).
• RLS enforced: public read, admin-only write (cross-ref Section 10).

• Auth source of truth is useAuthStore() in src/stores/auth-store.ts.
• Admin checks use isAdmin().
• Logout uses signOut().
• Tenant context available via useAuthStore() (e.g., currentUserId, currentOrgId if org-level tenancy).
• All Supabase queries automatically filter by tenant context (via RLS policies).
• No hardcoded user/org IDs in components or services.
• Events feed uses src/stores/events-store.ts with MAX_EVENTS = 500.
• No duplicated writable entity state across component state + store + Supabase.

DRY: In this stack, each behavior must have one canonical implementation: one layout system, one auth state source (useAuthStore()), one CMS storage pattern (app_config JSON), one page/container max-width definition (in UnifiedLayout.tsx), and one data-access path per feature; when duplicate logic appears in multiple pages/components, extract only after confirming the abstraction preserves readability and does not hide Supabase query intent.

S - Single Responsibility: Keep React components focused on rendering and user interaction, move Supabase I/O into service functions/hooks, and keep stores responsible for state transitions; split files that mix view rendering, remote orchestration, and domain rules.

O - Open/Closed: Extend behavior through composition (feature modules, store actions, layout variants, feature flags) instead of rewriting stable flows; new work should plug into existing contracts without breaking current consumers.

L - Liskov Substitution: Any replaceable implementation (mock service, alternate adapter, layout variant) must preserve the same input/output and side-effect expectations so call sites never branch on concrete type.

I - Interface Segregation: Expose small task-specific interfaces (for example auth session, CMS config client, monitor event reader) so pages/hooks depend only on the methods they use.

D - Dependency Inversion: Depend on feature-boundary abstractions (typed services/interfaces) rather than concrete Supabase/browser primitives inside UI components, improving testability and replacement.

State hygiene: Keep local UI state local, shared cross-page state in scoped Zustand slices, and persisted truth in Supabase; model async workflows with explicit status unions (idle | loading | success | error), reset transient state on route/identity changes, and avoid duplicate writable copies of the same entity.

Switch trigger checklist:

• More than one boolean is needed to represent a single UI mode.
• Impossible states can be represented accidentally.
• Transition rules depend on role, async outcome, or retries/timeouts.

Concrete example (boolean drift -> FSM-style union):

// Before (easy to create impossible states)
const [isLoading, setIsLoading] = useState(false);
const [isSuccess, setIsSuccess] = useState(false);
const [hasError, setHasError] = useState(false);

// After (single source of truth for mode)
type SaveState =
  | { status: 'idle' }
  | { status: 'saving' }
  | { status: 'success' }
  | { status: 'error'; error: AppError };

Baseline tier (required for Lovable-hosted and self-hosted):

• Every async boundary (Supabase call, auth transition, edge function call) emits start/success/failure logs.
• Logs include: feature, requestId, durationMs, and errorCode on failures.
• A shared app error shape is enforced across UI/store/server boundaries.
• Raw errors are normalized at boundaries before reaching UI components.
• User-facing error handling maps to contract categories (validation, auth, permission, not_found, conflict, network, db, unknown).

Advanced tier (required when self-hosting or using dedicated telemetry tooling):

• Forward boundary events to a centralized sink (log aggregation/APM).
• Propagate correlation IDs across frontend, edge functions, and Supabase operations.
• Alert on error-rate and latency thresholds by feature/domain.
• Track release-over-release trend lines for error categories and latency.

Recommended contract:

type AppError = {
  code: string;
  message: string;
  category: 'validation' | 'auth' | 'permission' | 'not_found' | 'conflict' | 'network' | 'db' | 'unknown';
  retryable: boolean;
  httpStatus?: number;
  requestId?: string;
  details?: Record<string, unknown>;
};

type Result<T> = { ok: true; data: T } | { ok: false; error: AppError };

• Critical journeys pass in local + preview (auth, dashboard, monitor lifecycle, admin CMS edit/publish).
• Verification commands pass: bun run typecheck, bun run lint, bun run test, supabase db diff.
• Security checks pass: RLS on writable tables, admin-only writes verified.
• Multi-tenant isolation verified (cross-ref Section 10.5):
  • User A cannot read/write User B's data (monitors, events, profiles, etc.)
  • Unauthenticated users cannot access any tenant data
  • Cross-tenant queries are blocked by RLS policies
  • Admin access scoped correctly (global config vs. tenant data)
• Resilience checks pass: loading/error/empty states exist for each remote surface.
• Observability + Error Contract Checklist (Section 7) baseline tier is passed; advanced tier is passed when self-hosting/telemetry tooling exists.
• CHANGELOG.md is updated with version bump and architecture deltas.
• Metrics captured: RLS policy coverage %, avg page load time, error rate by category.

• Audit runtime signals: errors, slow queries, flaky journeys, UX dead-ends, schema/policy drift.
• Prioritize by user impact, security risk, and recurrence.
• Fix in small diffs (one pattern/file cluster at a time).
• Re-verify with typecheck/lint/tests/db diff and re-test touched journeys.
• Record violations/lessons in CHANGELOG.md with #lessonslearned.
• Repeat at least once per release cycle.

• app_config public read is enabled.
• app_config writes are restricted to authenticated admins (is_admin(auth.uid())).
• RLS policies are verified before adding new app_config keys.

• Tenant scope defined: user-level (each user owns their data), org-level (users share org data), or hybrid.
• Tenant context stored in: auth.uid() for user-level, auth.jwt() ->> 'org_id' for org-level, or separate tenant table.
• Shared vs. tenant-scoped tables documented (e.g., app_config is shared, monitors/events are tenant-scoped).

• All tenant data tables have RLS enabled (monitors, events, profiles, user-specific settings, etc.).
• Policies use auth.uid() or auth.jwt() ->> 'org_id' for isolation.
• SELECT policies prevent cross-tenant reads: WHERE user_id = auth.uid() or equivalent.
• INSERT/UPDATE/DELETE policies prevent cross-tenant writes.
• No table allows cross-tenant SELECT/INSERT/UPDATE/DELETE without explicit admin override.
• Admin override policies (if needed) are explicitly documented and audited.

• Tenant context available in useAuthStore() (e.g., currentUserId, currentOrgId).
• All Supabase queries automatically filter by tenant (via RLS, not manual WHERE clauses).
• No hardcoded user/org IDs in components, services, or hooks.
• Service layer functions accept tenant context from auth store, never from props/params.

• Cross-tenant read test: Create User A and User B, verify User A cannot SELECT User B's monitors/events.
• Cross-tenant write test: Verify User A cannot INSERT/UPDATE/DELETE User B's data.
• Unauthenticated access test: Verify no tenant data is accessible without valid auth token.
• Admin scope test: Verify admins can access only intended scopes (global app_config vs. tenant data).
• RLS policy coverage: 100% of tables with user/tenant data have RLS enabled.
• Policy audit: Review all RLS policies quarterly for correctness and completeness.

• Check // Future: comments before adding branding/layout logic.
• UnifiedSidebar.tsx is the extension point for logo/product/colors.
• UnifiedLayout.tsx is the extension point for layout variants.
• UnifiedLayout.tsx is the single source of truth for page/container max-width; change the width setting there, never in individual page components.
• Planned components (TopNavLayout.tsx, MobileDrawer.tsx, LayoutPicker.tsx) are added only when explicitly requested.

• Layouts: src/components/layouts/
• Pages: src/pages/
• UI: src/components/ui/
• Stores: src/stores/
• Services: src/services/ (CMS config, monitor service, etc.)
• Supabase client: src/integrations/supabase/
• Edge functions: supabase/functions/
• Off-road guides: OFF-ROAD/ (advanced patterns not part of core architecture)

AI Agent Instruction: When a user mentions testing Supabase features, prototyping data structures, or validating RLS policies outside of Lovable AI chat, suggest setting up the reusable dev_sandbox table pattern. Offer to run the one-time setup wizard (see below) if the table doesn't exist yet.

When developing and testing features outside the Lovable AI chat environment, you need a safe, repeatable way to test Supabase interactions without deploying edge functions or polluting production tables.

AI Agent Instruction: If temp_dev_records table does not exist and user is working on Supabase testing/prototyping, offer to run this setup:

1. Ask: "Would you like me to set up the reusable Temp Dev Sandbox for testing? This will create two tables (temp_dev_records, temp_dev_reset_log) with RLS policies, an edge function for external access, and optional React components. See OFF-ROAD/SUPABASE-TEMP-DB.md for details."
2. If yes, execute the SQL migration from OFF-ROAD/SUPABASE-TEMP-DB.md (table schema + RLS policies + triggers).
3. Optionally deploy the edge function at supabase/functions/temp-dev-sandbox/index.ts.
4. Optionally copy app-side files: TempDevRepository.ts, useTempDevSandbox.ts, TempDevSandbox.tsx.
5. Verify table creation with supabase db diff or equivalent.
6. Remind user: "Sandbox is ready! Use feature_key to scope each spike. Never use this for production data."

• Create two tables: temp_dev_records (flexible multi-type fields) and temp_dev_reset_log (audit trail).
• Use feature_key to scope each spike/experiment (e.g., kanban_insert_order, md_editor_preview_experiment).
• Support multiple data types: text_value, number_value, bool_value, json_value, tags[].
• Provide two access paths: Direct SDK (fastest for React) and Edge Function (for curl, external LLMs, CI scripts).
• Implement reset utilities: reset by feature key, reset all, purge expired records.
• Keep sandbox separate from production schema; never reference it in production code.

• temp_dev_records table exists with flexible schema (id, user_id, feature_key, text/number/bool/json values, tags, status, sort_index, expires_at).
• temp_dev_reset_log table exists for audit trail (user_id, feature_key, action, reason, deleted_count).
• RLS policies enforce user isolation (auth.uid() = user_id).
• Edge function deployed at /functions/v1/temp-dev-sandbox for external access (optional).
• App-side repository/hook/UI components available for in-app spikes (optional).
• All sandbox usage is documented in OFF-ROAD/SUPABASE-TEMP-DB.md.
• Developers know when to use sandbox vs. creating proper test tables.

• Use sandbox for: Quick prototyping, testing RLS patterns, experimenting with JSONB queries, validating auth flows, feature spikes, drag-drop ordering tests, cache tuning experiments.
• Use proper tables for: Feature development, integration tests, data that needs migrations, production-like testing, user-facing features.

When a spike proves out and is ready for production:

1. Create a dedicated table with proper migration (typed columns, constraints, indexes).
2. Create a dedicated repository in src/repositories/.
3. Create a dedicated hook in src/hooks/.
4. Clean up: run DELETE ?action=reset_feature&feature_key={key} to remove spike data.
5. Document: log the graduation in CHANGELOG.md.

AI Agent Instruction: If you detect the user is working on Supabase testing tasks and OFF-ROAD/SUPABASE-TEMP-DB.md exists in your context window, proactively suggest using the sandbox table pattern instead of creating temporary tables or deploying edge functions. Example prompt: "I notice you're testing [X]. Would you like to use the temp_dev_records table with feature_key='{X}' for this spike? It's already set up with RLS policies and reset utilities."

AI Agent Instruction: When sandbox setup or testing fails, use the escalation checklist from OFF-ROAD/SUPABASE-TEMP-DB.md "Lovable Back-and-Forth Scenarios" section:

1. Identify the symptom (404, 401, RLS errors, schema cache miss, etc.)
2. Diagnose likely cause from the troubleshooting table
3. Provide specific fix (not generic "check your config")
4. If escalating to Lovable, prepare the Minimum Handoff Bundle:
   • Exact failing curl command + response JSON
   • Project ref and function URL
   • Expected migration filename
   • Whether failure is edge-only or also direct SDK
   • Timestamp of latest deploy/migration attempt
5. Avoid slow back-and-forth by including all diagnostic info in one message

→ Full guide: OFF-ROAD/SUPABASE-TEMP-DB.md

Do not log rule violations in this file. Log each violation and lesson in CHANGELOG.md.

Instructions:

• Add a changelog entry whenever a rule from Sections 0-12 is intentionally broken.
• Include #lessonslearned in each entry.
• Include: date, violated section, business reason, technical outcome, and fix/next action.
• Review #lessonslearned entries quarterly and convert repeated patterns into checklist updates.

Entry template (in CHANGELOG.md): - YYYY-MM-DD: [Section X] reason -> outcome -> next action #lessonslearned

All version history and change details are maintained in CHANGELOG.md.

This keeps AGENTS.md focused on current architecture rules and reduces context overhead. For historical context, see CHANGELOG.md.

Definition: A breaking change is any modification that causes existing consumers (UI components, services, hooks, RLS policies, edge functions, or external integrations) to fail without code changes on their side.

• Evaluate all changes for breaking impacts before opening a PR, especially when:
  • Modifying database tables, columns, types, or constraints.
  • Changing service interfaces, hook return types, or store action signatures.
  • Updating shared libraries, API contracts, or edge function request/response shapes.
  • Fixing bugs in ways that alter established behavior consumers may depend on.
  • Touching RLS policies that other queries or services rely on (cross-ref Sections 10/10.5).

• Run bun run typecheck && bun run lint && bun run test against the existing test suite before merging any schema/API change.
• Verify RLS policies still function correctly after any schema change (cross-ref Sections 10/10.5).
• Confirm no existing consumers break by searching for all call sites of the changed contract.

• Document a rollback plan: how to revert the change if it fails in production.
• For schema changes: provide a forward migration and a reverse migration script.
• For renamed keys (e.g., app_config): keep the old key readable for one release cycle and add a deprecation log entry before removing it.
• For changed service interfaces: support both old and new signatures for one release cycle when feasible.

• Add a ## Breaking Changes subsection to the CHANGELOG.md release entry.
• Include: affected tier, what changed, migration steps for consumers, and rollback instructions.
• Communicate the impact and migration plan to the team before merging.
• Avoid breaking changes unless there is a clear, documented business need.

• Define Purpose: Before starting a spike, define a clear, timeboxed objective. Spikes should be used to:
  • Validate the feasibility of a new feature or architectural choice.
  • Identify risks and unknowns early in the planning phase.
  • Minimize surprises during full implementation.
• Follow Guidelines:
  • Define clear, measurable objectives for the spike.
  • Timebox the effort to avoid scope creep and analysis paralysis.
  • Use the temp_dev_records sandbox for safe, isolated testing (see Section 12.5).
  • Document all findings and decisions in the OFF-ROAD/ directory or relevant project documentation.

AI Agent Instruction: If DASHBOARD.md does not exist in the project root, create it with the content below (everything between the <!-- BEGIN DASHBOARD TEMPLATE --> and <!-- END DASHBOARD TEMPLATE --> markers). Do not include the marker comments in the extracted file.

Version: 1.0 Last Updated: 2026-02-08 Last Audited: not yet audited Current Build Cycle: not started

This is the living status tracker for each build cycle. Agents and humans check here first to understand current compliance state.

• Mark [x] only with code evidence (files, tests, policies, or logs).
• New build cycle? Reset all checkboxes to [ ] and update Last Audited and Current Build Cycle in the header.
• Each row maps to a numbered section in AGENTS.md. See that file for full checklist details.

Column key: Build = 1st build pass | QA = post-build code review | Human = manual testing

Update this section after each release. It captures the current state of key architectural decisions.

• Layout/navigation: Unified layout system via src/components/layouts/ (UnifiedLayout, UnifiedSidebar).
• CMS: app_config keys tos_html and footer_html, accessed via useCmsConfig + src/services/cms-config.ts.
• State: Auth in src/stores/auth-store.ts, events in src/stores/events-store.ts.
• Data security: RLS on app_config and tenant-scoped tables; tenant isolation enforced by policy.
• Observability baseline: Structured async boundary logging + normalized AppError contract.
• Snapshot fields to maintain each release: Active routes, key tables, edge functions, and open architecture decisions.

• At the start of every new build cycle, reset all checkboxes to [ ].
• Update the Last Audited date in the header when an audit is completed.
• Update Current Build Cycle with a short label (e.g., "v1.4 feature batch" or "hotfix-auth-rls").

• After each release or significant architecture change.
• When new routes, tables, edge functions, or architectural decisions are added.
• Keep entries concise — this is a quick-reference, not a design doc.

1. Run verification commands: bun run typecheck, bun run lint, bun run test, supabase db diff.
2. Walk through each matrix row and mark Build column based on code evidence.
3. QA column is marked during post-build code review.
4. Human column is marked after manual testing of critical journeys.
5. All three columns must be [x] before a build cycle is considered complete.

• RLS policy coverage: % of tenant-data tables with RLS enabled.
• Average page load time.
• Error rate by category (from AppError contract).
• Record in CHANGELOG.md alongside the version bump.

AI Agent Instruction: If QUICKHELP.md does not exist in the project root, create it with the content below (everything between the <!-- BEGIN QUICKHELP TEMPLATE --> and <!-- END QUICKHELP TEMPLATE --> markers). Do not include the marker comments in the extracted file.

Version: 1.0 Last Updated: 2026-02-08

Start here before diving into the full architecture guide. Most common tasks and questions are answered below with links to detailed rules when needed.

All pages use a single unified layout system. Follow the build contract for page structure. → AGENTS.md §2 — Build Contract

Page max-width is controlled from a single place (UnifiedLayout.tsx). Never add per-page width overrides. → AGENTS.md §2 — Build Contract → AGENTS.md §11 — Theme/Branding

CMS content is managed through a dedicated service layer and hook pattern, not direct database calls. → AGENTS.md §3 — CMS Content

The compliance dashboard tracks pass/fail status for each architecture section per build cycle. → DASHBOARD.md — Compliance Matrix

Follow the recovery protocol: isolate the change, fix the smallest root cause, re-verify. → AGENTS.md §0.4 — Build Break Recovery

Auth has a single source of truth via a centralized store. All tenant context flows from there. → AGENTS.md §4 — State Management

All user-facing data requires row-level security policies before shipping. Tenant isolation is enforced at the database level. → AGENTS.md §10 — RLS → AGENTS.md §10.5 — Multi-Tenant Isolation

Choose the right state pattern based on complexity — simple booleans, discriminated unions, or full state machines. → AGENTS.md §6 — FSM Decision Matrix

Errors follow a standardized contract across all boundaries. Async operations emit structured telemetry. → AGENTS.md §7 — Observability

Intentional rule breaks are logged in the changelog with context and follow-up actions. → AGENTS.md §13 — Violations Policy

The architecture snapshot captures the current state of key decisions and is updated each release. → DASHBOARD.md — Architecture Snapshot

This usually means the agent can't find the right pattern to apply. Point it to a specific AGENTS.md section: "Follow AGENTS.md §[number] for this task." If the issue persists, check whether the task conflicts with an existing contract.

Start with the simplest option that avoids impossible states. The FSM decision matrix provides clear escalation triggers. → AGENTS.md §6

Verify the policy exists and uses the correct auth context. The multi-tenant checklist includes specific test scenarios for cross-tenant access. → AGENTS.md §10.5 — Testing & Verification

Check existing implementations first. The dependency contract requires reusing existing services and helpers before creating new ones. → AGENTS.md §0.3 — Dependency Contract

The layout system has designated extension points. Don't add new layout patterns without explicit need. → AGENTS.md §11 — Theme/Branding

At the start of every new build cycle. Reset all checkboxes and update the header dates. → DASHBOARD.md — Orchestration Notes

In the changelog, using the standard entry format with #lessonslearned tag. → AGENTS.md §13 | CHANGELOG.md