feat: configurable docs folders + mandatory instructions rules

config.yaml: new repo-root config file with docs_folders list
(docs, documentation, doc). apply.sh reads this list and picks the
first existing folder per project instead of hardcoding docs/.

Instructions:
- core-principles: add No Vibe Coding and No Touching .ai/ sections
- ai-root-instructions: add mandatory instructions block — rules stay
  active for the whole session, not just at start; AI must stop and
  announce if instructions were not loaded
- project-context, docs: updated to list all docs folder alternatives
  and reference config.yaml as the source of truth

FR-5.0 added to apply-requirements.md. README step 4 updated.

.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

.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
 
 ---
 

.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>/ai-context.md` | AI | Project context — architecture, decisions, pitfalls |
-| `docs/architecture.md` | Human + AI | System overview with Mermaid diagrams |
+| `<docs>/architecture.md` | Human + AI | System overview with Mermaid diagrams |
 
 ---
 

.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

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
 
 ```

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
+  # FR-5 + FR-6: docs — find existing folder or use default
-  local docs="$project/docs"
+  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] "

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

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)