diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..d37a85c
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,28 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx grunt:*)",
+      "Bash(npm install)",
+      "Bash(composer install)",
+      "Bash(./vendor/bin/phpcs:*)",
+      "Bash(git status)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(git push:*)",
+      "Bash(git remote:*)",
+      "Bash(ls:*)",
+      "Bash(find:*)",
+      "Bash(cat:*)",
+      "Bash(wc:*)"
+    ],
+    "deny": [
+      "Bash(rm -rf:*)",
+      "Bash(git push --force:*)",
+      "Bash(git reset --hard:*)"
+    ]
+  }
+}
diff --git a/.distignore b/.distignore
index 5f2c4bf..39febe4 100644
--- a/.distignore
+++ b/.distignore
@@ -31,3 +31,7 @@ node_modules
 package-lock.json
 .wordpress-org
 .github
+
+.claude
+CLAUDE.md
+internal-docs
diff --git a/.gitignore b/.gitignore
index b0b65e9..f2c70d6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,3 +30,5 @@ vendor/
 borders-for-default-menu.json
 defaults.json
 no-toggle-border-fix.json
+
+.claude/settings.local.json
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..10f2d77
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,55 @@
+# Astra Widgets
+
+## Project Overview
+
+Astra Widgets is a WordPress plugin by Brainstorm Force. Add address, social profiles, and list icon widgets to WordPress.
+
+- **Version:** 1.2.17
+- **Text Domain:** astra-widgets
+- **Main File:** astra-widgets.php
+- **Requires:** WordPress, PHP 5.6+
+
+## Tech Stack
+
+- **Language:** PHP
+- **Platform:** WordPress
+- **Build:** Grunt (i18n, readme conversion)
+- **Coding Standards:** PHPCS with WordPress standards
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+composer install
+
+# Build (i18n + readme)
+npx grunt
+
+# Generate translations
+npx grunt i18n
+
+# Convert readme.txt to README.md
+npx grunt readme
+
+# Run PHPCS
+./vendor/bin/phpcs .
+```
+
+## Architecture
+
+This is a WordPress plugin following standard WordPress patterns:
+- Entry point: `astra-widgets.php`
+- Constants defined for version, file path, base, dir, and URI
+- Classes loaded via `after_setup_theme` or `plugins_loaded` hook
+- Follows WordPress Coding Standards (WPCS)
+
+## Conventions
+
+- Use WordPress hooks (`add_action`, `add_filter`) for extensibility
+- Prefix all functions and classes to avoid conflicts
+- Use `astra-widgets` text domain for all translatable strings
+- Escape all output (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- Sanitize all input (`sanitize_text_field`, `absint`, etc.)
+- Use nonces for form submissions and AJAX requests
+- Follow WordPress PHP coding standards
diff --git a/Gruntfile.js b/Gruntfile.js
index 92ba749..fbcc08e 100644
--- a/Gruntfile.js
+++ b/Gruntfile.js
@@ -227,6 +227,9 @@ module.exports = function( grunt ) {
                         '!composer.lock',
                         '!package-lock.json',
                         '!phpcs.xml.dist',
+                        '!CLAUDE.md',
+                        '!.claude/**',
+                        '!internal-docs/**',
                     ],
                     dest: 'astra-widgets/'
                 }
diff --git a/internal-docs/README.md b/internal-docs/README.md
new file mode 100644
index 0000000..c0734f0
--- /dev/null
+++ b/internal-docs/README.md
@@ -0,0 +1,25 @@
+# Astra Widgets — Internal Documentation
+
+> Auto-generated documentation for developer onboarding and AI agent understanding.
+
+## Quick Facts
+
+| Key | Value |
+|-----|-------|
+| **Plugin Name** | Astra Widgets |
+| **Version** | 1.2.17 |
+| **Text Domain** | astra-widgets |
+| **Main File** | `astra-widgets.php` |
+| **PHP Files** | 12 |
+| **Build Tool** | Grunt |
+| **Stack** | WordPress Plugin (PHP) |
+
+## Description
+
+Add address, social profiles, and list icon widgets to WordPress.
+
+## Index
+
+- [Architecture](architecture.md) — High-level architecture and data flow
+- [Codebase Map](codebase-map.md) — Directory structure and key files
+- [AI Agent Guide](ai-agent-guide.md) — Key patterns and locations for AI-assisted development
diff --git a/internal-docs/ai-agent-guide.md b/internal-docs/ai-agent-guide.md
new file mode 100644
index 0000000..2ca457d
--- /dev/null
+++ b/internal-docs/ai-agent-guide.md
@@ -0,0 +1,40 @@
+# AI Agent Guide — Astra Widgets
+
+## Quick Start for AI Agents
+
+1. **Entry point:** Start at `astra-widgets.php` to understand plugin initialization
+2. **Constants:** Look for `define()` calls in the main file for paths and versions
+3. **Hook registration:** Search for `add_action` and `add_filter` to find where functionality is attached
+4. **Text domain:** Use `astra-widgets` for all translatable strings
+
+## Common Tasks
+
+### Adding a new feature
+1. Create a new class file in the appropriate directory
+2. Register it via `require_once` in the loader or main class
+3. Use `add_action`/`add_filter` to hook into WordPress
+4. Follow existing class patterns for consistency
+
+### Modifying existing behavior
+1. Find the relevant class by searching for the hook or function name
+2. Check for filters that allow modification without editing core files
+3. If editing, maintain the existing code style and patterns
+
+### Adding translatable strings
+1. Wrap strings in `__( 'text', 'astra-widgets' )` or `esc_html__( 'text', 'astra-widgets' )`
+2. Run `npx grunt i18n` to update the POT file
+
+## WordPress Checklist
+
+- [ ] All output is escaped (`esc_html`, `esc_attr`, `esc_url`, `wp_kses`)
+- [ ] All input is sanitized (`sanitize_text_field`, `absint`, etc.)
+- [ ] Nonces used for forms and AJAX (`wp_nonce_field`, `check_ajax_referer`)
+- [ ] Capability checks before privileged operations (`current_user_can`)
+- [ ] Text domain `astra-widgets` used for all user-facing strings
+- [ ] No direct file access (files start with `defined( 'ABSPATH' )` check or silence)
+
+## Pitfalls
+
+- Plugin may depend on Astra theme being active — check for theme dependency logic
+- Constants are defined only once — don't redefine them
+- Follow WordPress coding standards (spaces not tabs for alignment, tabs for indentation)
diff --git a/internal-docs/architecture.md b/internal-docs/architecture.md
new file mode 100644
index 0000000..e0188ff
--- /dev/null
+++ b/internal-docs/architecture.md
@@ -0,0 +1,32 @@
+# Architecture — Astra Widgets
+
+## Overview
+
+Astra Widgets is a WordPress plugin that follows standard WordPress plugin architecture patterns.
+
+## Entry Point
+
+The plugin entry point is `astra-widgets.php`, which:
+1. Defines plugin constants (version, file path, base name, directory, URI)
+2. Loads the main plugin class via a WordPress hook (`after_setup_theme` or `plugins_loaded`)
+
+## Request Lifecycle
+
+1. WordPress loads the plugin via `astra-widgets.php`
+2. Constants are defined for use throughout the plugin
+3. Main class is instantiated/loaded on the appropriate hook
+4. Classes register their own hooks and filters
+5. Frontend/admin output is rendered when WordPress fires the relevant hooks
+
+## Key Patterns
+
+- **Hook-based architecture:** All functionality is attached via `add_action()` and `add_filter()`
+- **Class autoloading:** Classes are loaded via `require_once` in the main plugin file or loader class
+- **Separation of concerns:** Admin and frontend code are separated into different classes/directories
+- **WordPress Customizer integration:** Settings are registered via the Customizer API where applicable
+
+## Dependencies
+
+- WordPress core (required)
+- Astra theme (recommended/required for full functionality)
+- No external PHP dependencies beyond WordPress
diff --git a/internal-docs/codebase-map.md b/internal-docs/codebase-map.md
new file mode 100644
index 0000000..84a1304
--- /dev/null
+++ b/internal-docs/codebase-map.md
@@ -0,0 +1,25 @@
+# Codebase Map — Astra Widgets
+
+## Directory Structure
+
+```
+astra-widgets/
+├── astra-widgets.php                    # Plugin entry point
+├── admin/bsf-analytics/class-bsf-analytics-loader.php
+├── admin/bsf-analytics/class-bsf-analytics-stats.php
+├── admin/bsf-analytics/class-bsf-analytics.php
+├── astra-widgets.php
+├── classes/class-astra-widgets-helper.php
+├── classes/class-astra-widgets-loader.php
+├── classes/class-astra-widgets.php
+├── classes/widgets/class-astra-widget-address.php
+├── classes/widgets/class-astra-widget-list-icons.php
+├── classes/widgets/class-astra-widget-social-profiles.php
+├── lib/astra-notices/class-astra-notices.php
+├── .distignore                            # WordPress.org distribution exclusions
+├── .gitignore                             # Git exclusions
+├── Gruntfile.js                           # Grunt build configuration
+├── package.json                           # Node.js dependencies
+├── CLAUDE.md                              # Claude Code project context
+└── .claude/settings.json                  # Claude Code tool permissions
+```