docs: add Directorist settings panel agent guide

.distignore

@@ -44,6 +44,7 @@
 /webpack.prod.js
 
 # Documentation & notes
+/docs
 /README.md
 /node-update-notes.md
 /CLAUDE.md

.gitattributes

@@ -2,6 +2,7 @@
 /.cache               export-ignore
 /.github              export-ignore
 /.wordpress-org       export-ignore
+/docs                 export-ignore
 
 /assets/src           export-ignore
 
@@ -27,4 +28,4 @@
 /webpack.prod.js         export-ignore
 
 # Merge strategy
-package.json merge=keep-local
+package.json merge=keep-local

AGENTS.md

@@ -236,6 +236,7 @@ Widgets: all-listing, all-categories, all-locations, category, location, tag, se
 **Save:** `wp_ajax_save_settings_data`
 **Options prefix:** `atbdp_` (legacy) and `directorist_` (new)
 **Features:** Import/export settings, restore defaults, per-directory-type settings, conditional field visibility (show-if)
+**Settings panel agent:** Before redesigning, auditing, or adding settings-panel features, load `docs/agents/directorist-settings-panel/SKILL.md` and follow its report-first workflow.
 
 ## Build Pipeline
 

CLAUDE.md

@@ -236,6 +236,7 @@ Widgets: all-listing, all-categories, all-locations, category, location, tag, se
 **Save:** `wp_ajax_save_settings_data`
 **Options prefix:** `atbdp_` (legacy) and `directorist_` (new)
 **Features:** Import/export settings, restore defaults, per-directory-type settings, conditional field visibility (show-if)
+**Settings panel agent:** Before redesigning, auditing, or adding settings-panel features, load `docs/agents/directorist-settings-panel/SKILL.md` and follow its report-first workflow.
 
 ## Build Pipeline
 

docs/agents/directorist-settings-panel/README.md

@@ -0,0 +1,73 @@
+# Directorist Settings Panel Agent Skill
+
+This folder contains a tracked repo-local skill/playbook for agents working on the Directorist settings panel. It is intentionally stored in `docs/agents/directorist-settings-panel/` because `.agents/` is ignored in this repo.
+
+## What This Skill Is For
+
+Use it when you want an agent to:
+
+- redesign the Directorist settings panel from a Figma design, screenshot, or idea
+- add a new settings-panel feature
+- add or adjust settings fields
+- audit settings-panel limitations before implementation
+- produce a report showing what is easy, what is complex, and what needs your decision
+
+## How To Use
+
+When starting a settings-panel task, tell the agent:
+
+```text
+Use docs/agents/directorist-settings-panel/SKILL.md for this task.
+```
+
+Then provide one of these:
+
+- a Figma node/link or screenshot
+- a written feature idea
+- the current problem you want solved
+- the settings page URL you want tested
+
+The agent should first inspect the current source, then produce a feasibility report before making code changes.
+
+## Expected First Output
+
+The first useful output should be a report with:
+
+- design or feature summary
+- what can be achieved easily
+- what is complex or risky
+- affected settings/data/UI areas
+- questions before risky work
+- verification plan
+
+If the change is visual-only and low risk, the report should say so. If the change affects storage, settings keys, AJAX save behavior, permissions, nonce handling, field contracts, layout structure, or extension-facing hooks, the agent must ask before implementation.
+
+## Build Policy
+
+The agent must not run these commands without your approval:
+
+- `npm run dev`
+- `npm run dev-vue`
+- `npm run prod`
+- any formatter or build command that rewrites tracked files
+
+Your preferred workflow is to run `npm run dev-vue` manually when needed. The agent can then use the local admin page for browser QA if the compiled output is available.
+
+## Local Settings URL
+
+Default local page for QA:
+
+```text
+http://directorist-core.local/wp-admin/edit.php?post_type=at_biz_dir&page=atbdp-settings
+```
+
+## Files In This Package
+
+- `SKILL.md`: the actual agent instructions
+- `references/current-settings-panel-map.md`: architecture map and known limitations
+- `references/settings-option-catalog.md`: grouped settings option map with purpose notes
+- `templates/feasibility-report.md`: reusable report template
+
+## Maintenance
+
+When a future settings-panel task reveals a confirmed architecture fact, limitation, or setting-key change, update the reference notes in this folder. Keep the skill concise and keep detailed discoveries in `references/`.

docs/agents/directorist-settings-panel/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: directorist-settings-panel-agent
+description: Use this skill whenever the user wants to redesign, extend, audit, or implement features in the Directorist WordPress plugin settings panel. Trigger for Directorist settings panel work, Figma-to-settings-panel tasks, wp-admin settings UI redesigns, adding settings fields, changing settings save behavior, or assessing whether a proposed settings feature is safe. This skill is intentionally strict: it must inspect the current settings architecture, produce a feasibility report first, and ask before risky structural changes.
+---
+
+# Directorist Settings Panel Agent
+
+This skill guides safe redesign and feature work for the Directorist settings panel. Directorist is production software used by many sites, so preserve existing behavior unless the user explicitly approves a structural change after seeing the risk.
+
+## Core Rule
+
+Always produce a report before implementation. Do not start code changes until the report identifies easy work, risky work, affected systems, and open questions for the user.
+
+## Required Context Pass
+
+Before planning or editing, inspect the current implementation in the local repo:
+
+- `includes/classes/class-settings-panel.php`
+- `views/admin-templates/settings-manager/settings.php`
+- `assets/src/js/admin/settings-manager.js`
+- `assets/src/js/admin/vue/apps/settings-manager/Settings_Manager.vue`
+- `assets/src/js/admin/vue/apps/settings-manager/TabContents.vue`
+- `assets/src/js/admin/vue/store/CPT_Manager_Store.js`
+- `assets/src/scss/layout/admin/settings-manager.scss`
+- `assets/src/scss/layout/admin/builder/_builder_style__settings_panel.scss`
+- `webpack-entry-list.js`
+
+Also search for any setting key or UI class named by the user before assuming where it lives.
+
+For bundled core modules that inject settings through filters, inspect the source that owns the injected section before planning:
+
+- Review settings: `includes/review/class-settings-screen.php`
+- Schema Markup settings: `includes/classes/class-schema.php`
+
+For any setting-key, section, or behavior change, also read:
+
+- `docs/agents/directorist-settings-panel/references/settings-option-catalog.md`
+
+If the task mentions extensions, extension settings, or a design inside the Extensions menu, first identify whether the target UI is core extension discovery or an installed extension's own settings. Extension-specific settings depend on the installed/active extension set.
+
+## Architecture Summary
+
+- PHP class `ATBDP_Settings_Panel` prepares settings fields, layouts, and config.
+- The admin template outputs base64-encoded JSON in `data-builder-data` on `#atbdp-settings-manager`.
+- `assets/src/js/admin/settings-manager.js` decodes that JSON and mounts the Vue 2 app.
+- `Settings_Manager.vue` renders the top bar, breadcrumbs, search, save buttons, sidebar, and tab contents.
+- `TabContents.vue` renders the active menu/submenu sections through globally registered Vue modules.
+- `CPT_Manager_Store.js` stores `fields`, `layouts`, `config`, cached field values, active navigation, and highlighted search results.
+- Settings save through the AJAX action `save_settings_data`.
+- Saved values are written into the shared WordPress option `atbdp_option`.
+- `directorist_options_updated` fires after option updates and can affect rewrite rules, cache, pages, emails, maps, listings, payments, and extensions.
+
+## Safety Rules
+
+- Do not run `npm run dev`, `npm run dev-vue`, `npm run prod`, formatters, code generators, or build commands that write tracked files unless the user explicitly approves.
+- If the user says they are manually running `npm run dev-vue`, use the generated output and browser QA, but do not start the command yourself.
+- Do not replace the settings system with a new framework or persistence layer.
+- Preserve the field/layout/config data contract unless the user approves a structural change.
+- Do not change settings keys, option storage, nonce handling, capability checks, AJAX action names, or `atbdp_option` behavior without explicit QA with the user.
+- Do not remove legacy `atbdp_` behavior just because new code prefers `directorist_`.
+- Keep generated build assets out of scope unless the user approves the required build command or specifically asks to edit committed build output.
+- Treat Figma as design intent, not a reason to rewrite data flow.
+
+## Work Classification
+
+Classify every requested change before implementation.
+
+Low risk:
+
+- Visual-only SCSS changes scoped to the settings panel.
+- Reordering or spacing within existing Vue structure without changing data flow.
+- Copy, typography, alignment, responsive layout, and focus-state improvements.
+- Search/breadcrumb/sidebar presentation changes that preserve existing store mutations.
+
+Medium risk:
+
+- Adding a new Vue-only interaction or UI state.
+- Adding a new reusable form-field component that uses existing save conventions.
+- Changing sidebar/search behavior while preserving hashes and layout paths.
+- Adding a setting field that stores a new key in `atbdp_option`.
+
+High risk:
+
+- Changing save payload shape, sanitization, nonce, or permissions.
+- Moving settings out of `atbdp_option`.
+- Changing layout JSON structure, field type contracts, or `show-if` behavior.
+- Changing page/permalink/map/payment/email settings because many frontend systems read them.
+- Changes that require migrations, upgrade routines, or extension compatibility decisions.
+
+Ask the user before medium-risk work if the report shows meaningful tradeoffs. Always ask before high-risk work.
+
+## Figma Or Design Workflow
+
+When the user provides a Figma design, screenshot, or visual reference:
+
+1. Inspect the existing settings implementation first.
+2. Extract layout, spacing, typography, color, navigation, and interaction intent.
+3. Map each design area to existing shell, sidebar, sections, and field components.
+4. Identify what can be achieved with SCSS/Vue template changes only.
+5. Identify any design detail that would require new data shape, new field type, or changed save behavior.
+6. Produce the required report and ask only the questions needed to resolve risky items.
+
+Prefer matching the design through the existing Vue/settings architecture. Do not rebuild the panel from scratch unless the user explicitly approves a rewrite.
+
+## Feature Workflow
+
+When the user asks for a new setting or behavior:
+
+1. Find existing related setting keys with `rg`.
+2. Check `references/settings-option-catalog.md` to understand the existing settings area and nearby option keys.
+3. Identify the connected frontend/admin systems that read those options.
+4. Decide whether the feature is UI-only, new setting storage, or behavior-changing.
+5. Confirm defaults, backward compatibility, and migration needs before editing.
+6. Use existing field types and `show-if` conventions when possible.
+7. If adding, removing, renaming, moving, or repurposing a key, update the settings option catalog after the implementation is confirmed.
+8. If adding a new key, document default value, sanitize behavior, and all readers.
+
+## Extension Settings Workflow
+
+The `Extensions` menu is core, but many extension-specific settings are not present unless the related Directorist extension is installed and active.
+
+When a design or feature targets extension UI/settings:
+
+1. Identify the exact extension name/slug from the user's design, URL, screenshot, or installed plugins list.
+2. Inspect active plugins and extension filter usage before treating any setting as available.
+3. If the required extension is missing or inactive, ask the user before installing or activating it.
+4. After the extension is active, inspect its filters, setting fields, layouts, templates, scripts, and styles.
+5. Produce the feasibility report using both core settings-panel context and extension-specific source context.
+6. Do not document extension-provided settings as core. Add them to the catalog only under an extension-specific heading after source/filter evidence confirms them.
+7. If the design could affect multiple extensions, ask for the target extension before implementation.
+
+## Required Report Template
+
+Use this exact structure before implementation:
+
+```markdown
+# Settings Panel Feasibility Report
+
+## Summary
+- Request:
+- Recommended approach:
+- Risk level:
+
+## Easy To Achieve
+- ...
+
+## Complex Or Risky
+- ...
+
+## Affected Areas
+- PHP settings builder:
+- Vue app/store:
+- SCSS/build output:
+- Saved options/data:
+- Connected frontend/admin behavior:
+
+## Questions Before Risky Work
+- ...
+
+## Verification Plan
+- Static checks:
+- Browser/manual QA:
+- Build policy:
+```
+
+If there are no risky questions, say that clearly and proceed only if the active collaboration mode allows implementation.
+
+## Verification Expectations
+
+Use the smallest verification set that matches the change:
+
+- Static inspection with `rg`, `git diff`, and focused file reads.
+- PHP syntax checks for touched PHP files.
+- Browser QA on the local settings URL when available:
+  `http://directorist-core.local/wp-admin/edit.php?post_type=at_biz_dir&page=atbdp-settings`
+- Confirm save still posts to `save_settings_data` and unchanged fields are not rewritten unnecessarily.
+- Confirm responsive behavior at desktop and mobile widths for visual redesign work.
+- Confirm no build commands were run unless the user approved them.
+
+## Self-Learning Protocol
+
+Self-learning is tracked-reference learning, not automatic memory. The agent learns only when it updates files in this package with confirmed repo facts.
+
+Update the tracked references when:
+
+- a settings-panel task confirms a new architecture fact, limitation, dependency, or regression pattern
+- a setting key is added, removed, renamed, moved between sections, or given new behavior
+- a core module injects settings through filters and the catalog does not yet identify that source
+- an installed extension adds settings through filters and the user approves documenting that extension-specific behavior
+- a Figma/design implementation reveals a reusable UI constraint or compatibility issue
+- a verification step discovers a required QA path that future agents should repeat
+
+Only record confirmed learning:
+
+- facts observed in source code, diffs, browser QA, tests, or user-approved decisions
+- exact file paths, option keys, hooks, filters, routes, and build constraints
+- current behavior with the review date when the behavior may change later
+
+Do not record:
+
+- guesses, opinions, or unverified assumptions as architecture facts
+- temporary implementation details that were reverted or not accepted
+- user-private context that is not needed for future repo work
+- broad lessons that are not specific to the Directorist settings panel
+
+Keep learning useful:
+
+- put architecture and constraints in `references/current-settings-panel-map.md`
+- put setting areas, keys, and purposes in `references/settings-option-catalog.md`
+- keep `SKILL.md` short and workflow-focused
+- update references after the code/design decision is confirmed, not before