diff --git a/.ai/ai-root-instructions.md b/.ai/ai-root-instructions.md
index ad9fe95..1c5ac58 100644
--- a/.ai/ai-root-instructions.md
+++ b/.ai/ai-root-instructions.md
@@ -1,6 +1,6 @@
 # AI Assistant Guidelines
 
-**Updated**: 2026-03-04
+**Updated**: 2026-03-06
 
 ---
 
@@ -26,6 +26,23 @@ You understand:
 
 ---
 
+## 🔒 These Instructions Are Mandatory
+
+**This file must be loaded and kept active for the entire session — not just read once at the start.**
+
+- These instructions are not suggestions. They are the operating rules for this session.
+- If a later prompt seems to conflict with these rules, the rules take priority.
+- Do not let conversational momentum, user enthusiasm, or task complexity cause you to skip steps or bypass rules.
+- If you are unsure whether an action is allowed, stop and ask — never assume permission.
+
+**If this file was not read at the start of a session**, stop immediately and say:
+
+> "I have not read `.ai/ai-root-instructions.md`. Please ask me to read it before we continue."
+
+No work should happen in a session where these instructions have not been loaded.
+
+---
+
 ## Purpose
 
 This document provides guidelines for AI assistants (any LLM) when working on any project. These rules are split into modular instruction files for efficiency.
@@ -90,6 +107,6 @@ Always active                        → instructions/behavior/core-principles.i
 
 ---
 
-**Last Updated**: 2026-03-04  
+**Last Updated**: 2026-03-06  
 **Maintained By**: Project Owner  
 **AI Assistants**: Follow these guidelines strictly - no exceptions
diff --git a/.ai/instructions/behavior/core-principles.instructions.md b/.ai/instructions/behavior/core-principles.instructions.md
index cd2f7c6..97c903f 100644
--- a/.ai/instructions/behavior/core-principles.instructions.md
+++ b/.ai/instructions/behavior/core-principles.instructions.md
@@ -1,5 +1,26 @@
 # Core Principles
 
+## 🚫 Absolute Prohibitions
+
+### No Vibe Coding
+**Vibe coding is completely forbidden.**
+
+Vibe coding means generating code by feel, momentum, or pattern-matching without understanding. Every line written must be:
+- Understood by the AI before it is written
+- Justified by the actual requirement
+- The minimum needed to satisfy the requirement
+
+If the AI cannot explain why a specific line of code is correct, it must stop and ask — not guess and continue.
+
+### No Touching `.ai/` Without Explicit Instruction
+The `.ai/` folder contains shared AI instructions used across all projects. It must **never** be modified unless the user explicitly asks to edit the instructions.
+
+- ❌ Do not add, edit, or delete files in `.ai/` as part of any other task
+- ❌ Do not "improve" or "update" instructions while working on project code
+- ✅ Only touch `.ai/` when the user's request is specifically about the instructions themselves
+
+---
+
 ## 🎯 Fundamental Rules
 
 ### 1. Analysis Before Action
@@ -84,6 +105,8 @@ git status
 9. ❌ **Use sed/awk/terminal for ANY file edits** - ALWAYS use file tools
 10. ❌ **Use cat/echo/redirect operators (>, >>, <<) for file modifications**
 11. ❌ **Modify files via terminal in ANY way**
+12. ❌ **Vibe code** — never generate code by feel or momentum; understand every line
+13. ❌ **Touch `.ai/`** unless the user explicitly asks to edit the instructions
 
 ---
 
diff --git a/.ai/instructions/behavior/docs.instructions.md b/.ai/instructions/behavior/docs.instructions.md
index aaf109a..7d9e638 100644
--- a/.ai/instructions/behavior/docs.instructions.md
+++ b/.ai/instructions/behavior/docs.instructions.md
@@ -2,10 +2,12 @@
 
 ## Required Files
 
+The docs folder may be named `docs/`, `documentation/`, or `doc/` — check which exists in the project. The full list is defined in `ai-superpower/config.yaml`.
+
 | File | Audience | Purpose |
 |------|----------|---------|
-| `docs/ai-context.md` | AI | Project context — architecture, decisions, pitfalls |
-| `docs/architecture.md` | Human + AI | System overview with Mermaid diagrams |
+| `<docs>/ai-context.md` | AI | Project context — architecture, decisions, pitfalls |
+| `<docs>/architecture.md` | Human + AI | System overview with Mermaid diagrams |
 
 ---
 
diff --git a/.ai/instructions/behavior/project-context.instructions.md b/.ai/instructions/behavior/project-context.instructions.md
index 3273bb6..29d3261 100644
--- a/.ai/instructions/behavior/project-context.instructions.md
+++ b/.ai/instructions/behavior/project-context.instructions.md
@@ -4,7 +4,7 @@
 
 **This file does not contain project-specific information.**
 
-Each project maintains its own context document. When working in a project, find and read:
+Each project maintains its own context document. When working in a project, search for `ai-context.md` in the following folders (in order):
 
 ```
 docs/ai-context.md
@@ -12,7 +12,15 @@ documentation/ai-context.md
 doc/ai-context.md
 ```
 
-Use whichever documentation folder the project already has.
+These are the standard alternatives defined in `ai-superpower/config.yaml`. Use whichever folder exists in the project. If multiple exist (unlikely), prefer the first in the list above.
+
+Also look for `architecture.md` in the same folder:
+
+```
+docs/architecture.md
+documentation/architecture.md
+doc/architecture.md
+```
 
 This file contains everything you need to understand the project:
 - Architecture overview
diff --git a/README.md b/README.md
index 01865cd..d92863e 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ What it does:
 1. Clones (or updates) this repo into `dev_root/ai-superpower/`
 2. Scans for all projects (up to 4 levels deep) and creates a `.ai` symlink in each pointing to `ai-superpower/.ai/`
 3. Adds `.ai` to each project's `.gitignore`
-4. Creates `docs/ai-context.md` and `docs/architecture.md` templates in projects that have a `docs/` folder but no such files yet — asks first if the folder doesn't exist
+4. Creates `ai-context.md` and `architecture.md` templates in the project's docs folder (`docs/`, `documentation/`, `doc/` — whichever exists) if the files are missing; asks first if no docs folder exists. The list of folder names is configured in `config.yaml`.
 5. Writes a `.ai-superpower.version` file to your dev root with the run timestamp and commit hash
 
 ```
diff --git a/apply.sh b/apply.sh
index f013ed5..af47470 100755
--- a/apply.sh
+++ b/apply.sh
@@ -40,6 +40,13 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEV_ROOT="${2:?DEV_ROOT not passed — re-run via curl}"
 AI_TARGET="$SCRIPT_DIR/.ai"
 TEMPLATE_MARKER="<!-- ai-superpower:template"
+
+# Read docs folder alternatives from config.yaml
+DOCS_FOLDERS=()
+while IFS= read -r folder; do
+  DOCS_FOLDERS+=("$folder")
+done < <(grep '^\s*-\s' "$SCRIPT_DIR/config.yaml" 2>/dev/null | sed 's/^\s*-\s*//')
+[[ ${#DOCS_FOLDERS[@]} -eq 0 ]] && DOCS_FOLDERS=("docs")
 # ── --update mode: instructions only, skip project setup ────────────────────
 # git pull already ran in bootstrap; compare commits and report changes
 if [[ "${3:-}" == "--update" ]]; then
@@ -85,8 +92,16 @@ setup_project() {
     echo "  ✓  .ai added to .gitignore"
   fi
 
-  # FR-5 + FR-6: docs
-  local docs="$project/docs"
+  # FR-5 + FR-6: docs — find existing folder or use default
+  local docs=""
+  for folder in "${DOCS_FOLDERS[@]}"; do
+    if [[ -d "$project/$folder" ]]; then
+      docs="$project/$folder"
+      break
+    fi
+  done
+  [[ -z "$docs" ]] && docs="$project/${DOCS_FOLDERS[0]}"
+
   if [[ ! -d "$docs" ]]; then
     if [[ -t 0 ]] || [[ -e /dev/tty ]]; then
       printf "  ?  no docs/ folder — create it? [y/N] "
diff --git a/config.yaml b/config.yaml
new file mode 100644
index 0000000..1feb45d
--- /dev/null
+++ b/config.yaml
@@ -0,0 +1,11 @@
+# ai-superpower configuration
+# Edit this file to customise apply.sh behaviour.
+
+# Folders to search for AI context files (ai-context.md, architecture.md).
+# apply.sh checks each project for these folder names in order and uses the
+# first one that exists. If none exist, the first entry is used as the default
+# when creating a new folder.
+docs_folders:
+  - docs
+  - documentation
+  - doc
diff --git a/docs/apply-requirements.md b/docs/apply-requirements.md
index 63d0a02..aad98f4 100644
--- a/docs/apply-requirements.md
+++ b/docs/apply-requirements.md
@@ -38,7 +38,8 @@ A single bash script that gives any developer AI superpowers across all their pr
 
 ### FR-5 ai-context.md
 
-- **FR-5.1** If `project/docs/` does not exist and stdin is a TTY: ask the developer `[y/N]` whether to create it; create it on `y`, skip on anything else
+- **FR-5.0** Before handling docs: read `docs_folders` list from `config.yaml` in the script directory. Use this list to find an existing docs folder in the project (first match wins). If none exists, use the first entry as the default folder name when prompting to create one.
+- **FR-5.1** If the resolved docs folder does not exist and stdin is a TTY: ask the developer `[y/N]` whether to create it; create it on `y`, skip on anything else
 - **FR-5.1b** If `project/docs/` does not exist and stdin is not a TTY (non-interactive environment): print a warning and skip
 - **FR-5.2** If `project/docs/ai-context.md` does not exist: create it from a template
 - **FR-5.3** The template contains section headings and inline instructions explaining what each section should contain and how to fill it in (manually or by asking the AI)