docs(research): add plain-language summaries and guide

Author: danielcadev

README.academic.md

@@ -8,6 +8,7 @@ The repository combines a working Next.js CMS platform with a documented archite
 
 Quick links:
 
+- Research guide: [docs/research/README.md](./docs/research/README.md)
 - Executive summary: [docs/research/executive-summary.md](./docs/research/executive-summary.md)
 - Vibe-Guard protocol: [docs/vibe-guard/protocol-overview.md](./docs/vibe-guard/protocol-overview.md)
 - Commercial version: [README.commercial.md](./README.commercial.md)

README.md

@@ -15,6 +15,7 @@ It combines three goals in one repository:
 - Commercial overview: [README.commercial.md](./README.commercial.md)
 - Academic overview: [README.academic.md](./README.academic.md)
 - Developer guide: [docs/dev/README.md](./docs/dev/README.md)
+- Research guide: [docs/research/README.md](./docs/research/README.md)
 - Docs index: [docs/README.md](./docs/README.md)
 - Security audit: [docs/security/security-audit.md](./docs/security/security-audit.md)
 - Vibe-Guard protocol: [docs/vibe-guard/protocol-overview.md](./docs/vibe-guard/protocol-overview.md)

docs/README.md

@@ -26,6 +26,7 @@ If you’re reading the repository as a research artifact, jump to the Research
 
 ## Research
 
+- [Research Guide (Start Here)](./research/README.md)
 - [Executive Summary](./research/executive-summary.md)
 - [Core Concepts](./research/core-concepts.md)
 - [Methodology](./research/methodology.md)

docs/dev/README.md

@@ -2,7 +2,7 @@
 
 This guide is for engineers using `CMS Nova` as a reusable Next.js CMS template (not the research angle).
 
-If you’re here for the case study / Vibe-Guard research docs, start at `docs/research/executive-summary.md`.
+If you’re here for the case study / Vibe-Guard research docs, start at `docs/research/README.md`.
 
 ## Quick Start (Local)
 

docs/research/README.md

@@ -0,0 +1,45 @@
+# Research Guide (Start Here)
+
+This folder documents a case study about security and architectural integrity in **AI-assisted software development**, using `CMS Nova` as the main research artifact.
+
+## TL;DR (1 minute)
+
+- AI coding can produce changes that look correct **inside one file**, but violate **system-wide security rules** (auth boundaries, publication rules, route visibility, secret handling).
+- The case study identifies recurring reasoning failures (e.g. `Naming Bias`, `Lack of Global Context`) and frames the human role as `MVU` (Minimum Viable Understanding).
+- The proposed mitigation is `Vibe-Guard`: treat security as **policy verification** (central rules + automated checks), not as “remember everything everywhere”.
+- This repo includes a small concrete example of that idea: a default-private policy for `/api/*` routes plus a static checker (`npm run security:check-api`).
+
+## Plain-language (ELI5)
+
+Imagine a helper who is very good at building **one LEGO house at a time**.
+Each house looks fine. But a city is not just houses — it also has **city rules**:
+
+- “Only teachers can enter the teacher room.” (authorization)
+- “Only finished posters go on the public wall.” (published-only content)
+- “Don’t put secret keys on the street.” (secret handling)
+
+AI tools often follow the “house logic” but forget the “city rules” unless those rules are written down and checked.
+`Vibe-Guard` is the idea of writing the city rules once, centrally, and having an automated guard verify that every new house still follows them.
+
+## What’s in This Repo (Research Artifacts)
+
+- Concepts and framing:
+  - [Core Concepts](./core-concepts.md)
+- Evidence and narrative:
+  - [Case Study: CMS Nova](./case-study-cms-nova.md)
+  - [Findings Matrix](./findings-matrix.md)
+- Method and reproducibility:
+  - [Methodology](./methodology.md)
+  - [API Visibility Policy](../../src/server/policy/api-visibility.js)
+  - [API Policy Checker](../../scripts/security/check-api-policy.js)
+- Architecture intervention record:
+  - [Architecture Evolution](./architecture-evolution.md)
+
+## Suggested Reading Order
+
+1. [Executive Summary](./executive-summary.md)
+2. [Core Concepts](./core-concepts.md)
+3. [Case Study: CMS Nova](./case-study-cms-nova.md)
+4. [Methodology](./methodology.md)
+5. [Findings Matrix](./findings-matrix.md)
+6. [Architecture Evolution](./architecture-evolution.md)

docs/research/architecture-evolution.md

@@ -1,5 +1,17 @@
 # Architecture Evolution
 
+## TL;DR (1 minute)
+
+- The initial repo worked, but boundaries were blurry: server/client concerns mixed, public/admin rules scattered, and business-specific features leaked into “core”.
+- The intervention encodes boundaries in folders (`server/`, `modules/`, `shared/`, `verticals/`) and makes policy-sensitive behavior harder to change accidentally.
+- This supports the research thesis: AI can keep local code correct while eroding global integrity unless architecture + policy are explicit.
+
+## Plain-language (ELI5)
+
+Think of the repo like a big house.
+If everything is thrown into one big room, it’s easy to accidentally grab the wrong thing and break a rule.
+By putting things into labeled rooms (server-only, shared, business-specific), we make it easier for humans and tools to follow “house rules” consistently.
+
 ## Purpose
 
 This document explains the structural evolution of `CMS Nova` from an organically grown application into a more explicit platform architecture. It is written as both a technical record and a research artifact for the Vibe-Guard case study.

docs/research/case-study-cms-nova.md

@@ -1,5 +1,18 @@
 # Case Study: CMS Nova
 
+## TL;DR (1 minute)
+
+- AI-assisted changes can improve one visible security issue while silently weakening another cross-cutting rule.
+- The most common failures were not “syntax bugs”, but **policy bugs**: what should be public, who can mutate state, what counts as “published”, and where secrets/logs can go.
+- This repo includes a small “default private” guardrail for `/api/*` routes as an example of policy externalization.
+
+## Plain-language (ELI5)
+
+`CMS Nova` is like a school with many rooms.
+Some rooms are public (hallway), some are private (teacher office).
+AI helpers often build features fast, but sometimes they accidentally leave a door unlocked because the door is in a different file than the feature they were working on.
+The case study is about finding those “unlocked doors” and then writing down rules so they are harder to reintroduce.
+
 ## Why CMS Nova Matters
 
 `CMS Nova` is a strong research artifact because it is neither a toy example nor a narrowly scoped demo. It contains dynamic content modeling, authentication, admin workflows, plugin configuration, public routing, file handling, and productization efforts through a CLI. That combination makes it large enough for structural failures to emerge.

docs/research/core-concepts.md

@@ -1,5 +1,12 @@
 # Core Concepts
 
+## Plain-language (ELI5)
+
+- **Naming Bias:** trusting the *label* on a box instead of checking what’s inside.
+- **Lack of Global Context:** fixing one room in a house without understanding how the whole house works.
+- **MVU:** the minimum “map” a human needs to notice when something is locally fine but globally unsafe.
+- **Vibe-Guard:** a rulebook + a referee (central rules that can be checked automatically).
+
 ## Naming Bias
 
 `Naming Bias` describes the tendency of AI coding systems to use names as security signals. If a file, route, variable, or module sounds harmless, the model may infer that it is safe to expose, relax, or bypass. This inference is often made without validating the actual sensitivity of the underlying data or checking project-wide policies.

docs/research/executive-summary.md

@@ -1,5 +1,19 @@
 # Executive Summary
 
+## TL;DR (1 minute)
+
+- AI-assisted coding can generate changes that look correct **inside one file**, but break **system-wide security rules** (auth boundaries, publication rules, route visibility, secret handling).
+- `CMS Nova` is used as a realistic case study; audits of AI-assisted paths surfaced **24 vulnerabilities** across multiple systems.
+- The proposed mitigation is `Vibe-Guard`: move critical expectations into **central policy** and check changes against them automatically.
+
+## Plain-language (ELI5)
+
+Think of software like a big LEGO city.
+An AI helper can build one LEGO house very fast, and that house can look “correct”.
+But cities also have rules: “only grown-ups can open this door” and “don’t put secrets outside”.
+AI systems often follow the house-level logic but forget the city-level rules unless those rules are written down and checked.
+`Vibe-Guard` is the idea of writing the city rules once and having an automated guard verify every change.
+
 This research investigates the security behavior of AI-assisted software development through a real-world case study: `CMS Nova`, a Next.js-based headless CMS that evolved through iterative human-AI collaboration.
 
 The central claim is that modern coding models often preserve local correctness while weakening global system integrity. In practice, they can produce working code that appears reasonable inside a single file, yet violates cross-cutting security invariants such as authorization boundaries, publication rules, route exposure constraints, and secret-handling policies.

docs/research/findings-matrix.md

@@ -1,5 +1,16 @@
 # Findings Matrix
 
+## How to Use This (30 seconds)
+
+- Each row is one “what went wrong” story: **Issue → Root cause → AI failure mode → Intervention → Outcome**.
+- Read it as a map from *symptom* to *structural fix*, not as a list of random bugs.
+- If you only read one thing: look for repeated patterns in the **AI Failure Mode** column.
+
+## Plain-language (ELI5)
+
+This table is like a “mistake notebook”.
+It lists the same kind of mistakes happening again and again (e.g., leaving a door unlocked), and then shows the fix (e.g., adding a lock that is checked every time).
+
 ## Purpose
 
 This matrix summarizes the main findings from the `CMS Nova` case study in a format suitable for research writing, portfolio presentation, and discussion of the Vibe-Guard proposal.