# Documentation Standard (LOCKED)

This document is the single source of truth for the structure and format of all
documentation in this repository. **No deviation is permitted.** Any new or
modified content must conform to this standard exactly.

Status: **LOCKED** — changes to this standard require explicit user approval.

---

## 1. Repository Structure

```
mi digital new platform/
├── .gitignore
├── Mi Digital Academy - Education CRM Features Document (2).pdf   ← source document (read-only reference)
├── project.md                                                     ← project overview + user types
├── documentation_standard.md                                      ← this file (the locked standard)
├── super_admin/                                                   ← Super Administrator panel
│   ├── super_administrator.md                                     ← master list of all 24 modules
│   ├── <module>.md                                                ← slim index (one per module)
│   └── <module>/                                                  ← feature files + test files (one folder per module)
│       ├── <feature_group_1>.md
│       ├── <feature_group_1>_tests.md
│       ├── <feature_group_2>.md
│       ├── <feature_group_2>_tests.md
│       └── ...
├── student/                                                       ← Student panel (identical structure)
│   ├── student.md                                                 ← master list of all modules
│   ├── <module>.md                                                ← slim index (one per module)
│   └── <module>/                                                  ← feature files + test files
├── parent/                                                        ← Parent panel (identical structure)
│   ├── parent.md                                                  ← master list of all modules
│   ├── <module>.md                                                ← slim index (one per module)
│   └── <module>/                                                  ← feature files + test files
├── affiliate/                                                     ← Affiliate panel (identical structure)
│   ├── affiliate.md                                               ← master list of all modules
│   ├── <module>.md                                                ← slim index (one per module)
│   └── <module>/                                                  ← feature files + test files
├── training_institute/                                            ← Training Institute panel (identical structure)
│   ├── training_institute.md                                      ← master list of all modules
│   ├── <module>.md                                                ← slim index (one per module)
│   └── <module>/                                                  ← feature files + test files
└── autopilot_decisions.md                                         ← log of documented autopilot decisions
```

Rules:
- One folder per module, named in **snake_case** (e.g., `pricing_management/`).
- The module's slim index file sits **next to** its folder, with the same base name
  (e.g., `pricing_management.md` + `pricing_management/`).
- Inside each module folder: **exactly one feature file per feature group**, named
  in **snake_case** after the feature group (e.g., `academic_pricing.md`), plus
  **exactly one test case file per feature group** named
  `<feature_group>_tests.md` (e.g., `academic_pricing_tests.md`).
- No other files, folders, or nesting levels are permitted inside module folders.
- Each user type has a master list that lists all of that user type's modules in
  dependency order: `super_admin/super_administrator.md` for Super Admin, and
  `<user_type>/<user_type>.md` for the other user types (e.g., `student/student.md`).
  A master list is NOT a slim index and has no `## Feature Documents` section.
- The process, formats, depth, content rules, git rules, and verification
  checklist are IDENTICAL for every user type. Only the perspective (User Type)
  changes.

## 2. Current Inventory (locked baseline)

### Super Administrator (complete)

| Level | Count |
|-------|-------|
| Modules | 24 |
| Feature groups (files in module folders) | 146 |
| Features (`### X.Y` headings) | 493 |
| Sub-features (bullets) | 6,648 |
| Test case files (`<feature_group>_tests.md`) | 146 |
| Test cases (`### TC-SA-` blocks) | 4,280 |

### Other user types (build order: Student → Parent → Affiliate → Training Institute)

| User type | Modules | Feature groups | Features | Sub-features | Test case files | Test cases |
|-----------|---------|----------------|----------|--------------|-----------------|------------|
| Student | 15 | 60 | 181 | 1,578 | 60 | 1,578 |
| Parent | 10 | 40 | 119 | 947 | 40 | 947 |
| Affiliate | 9 | 36 | 108 | 887 | 36 | 887 |
| Training Institute | 9 | 36 | 108 | 946 | 36 | 946 |

Counts for each user type are filled in and committed as that user type is
completed. Each user type's module list is derived from the PDF's own sections
for that user type (the PDF is the source of truth).

**Status: all five user types are complete** (Super Admin, Student, Parent,
Affiliate, Training Institute).

Every feature group file contains one or more features. Every feature contains all
four required sections (Section 5). No feature may be missing any section.

## 3. Naming Conventions

- User type folders: `super_admin/`, `student/`, `parent/`, `affiliate/`,
  `training_institute/`. Master list files: `super_administrator.md` (inside
  `super_admin/`) and `<user_type>.md` (inside each other user type folder).
- Folders and files: **snake_case**, lowercase, underscores (e.g., `backup_data_export/`,
  `data_portability.md`).
- Feature group file name = snake_case of the feature group name
  (e.g., "Academic Pricing" → `academic_pricing.md`).
- Test case file name = feature group file name + `_tests`
  (e.g., `academic_pricing.md` → `academic_pricing_tests.md`).
- No spaces, no camelCase, no hyphens in file or folder names.

## 4. Slim Index Format (module `.md` file)

Exact template — no additions, no reordering:

```markdown
# Module: <Module Name>

User Type: **<User Type>**
Source: *Mi Digital Academy - Education CRM Features Document*

All features and functionalities of this module, strictly feature and function based.

## 1. <Feature Group 1 Name>
- <bullet>
- <bullet>

## 2. <Feature Group 2 Name>
- <bullet>

...

## Feature Documents

Detailed specifications for each feature group (in `<module_folder>/`):

1. [<Feature Group 1 Name>](<module_folder>/<file_1>.md)
   - Test Cases: [<file_1>_tests.md](<module_folder>/<file_1>_tests.md)
2. [<Feature Group 2 Name>](<module_folder>/<file_2>.md)
   - Test Cases: [<file_2>_tests.md](<module_folder>/<file_2>_tests.md)
...
```

Rules:
- The numbered `## N. <Feature Group>` sections list every feature group with its
  overview bullets, in the same order as the feature files.
- The `## Feature Documents` section is the LAST section. It contains one numbered
  link per feature group, in the same order, each immediately followed by an
  indented `   - Test Cases:` link to that group's test file.
- **Invariant:** the number of `## N.` group sections MUST equal the number of
  feature links in `## Feature Documents` AND the number of feature files in the
  module folder. The number of Test Cases links MUST equal the number of test
  files in the module folder.

## 5. Feature File Format

### 5.1 File Header (exact)

```markdown
# N. <Feature Group Name>

User Type: **<User Type>**
Source: *Mi Digital Academy - Education CRM Features Document*

---

## N. <Feature Group Name>
```

- `N` is the feature group's number within its module (matching the slim index).
- Both the H1 (`# N.`) and H2 (`## N.`) lines are required, with identical text.
- The `---` separator is required between the header block and the H2.

### 5.2 Feature Section (exact, per feature)

Every feature uses this exact structure, in this exact order:

```markdown
### X.Y <Feature Name>

**What it does:** <complete behavioral paragraph>

**Sub-features:**
- <sub-feature bullet>
- <sub-feature bullet>
...

**<User Type> User Journey:**
1. <step>
2. <step>
...

**Rules & Edge Cases:**
- <rule bullet>
- <rule bullet>
...
```

Rules:
- Feature numbering is `X.Y` where X = feature group number, Y = sequential within
  the group (1.1, 1.2, ... 2.1, 2.2, ...).
- **What it does:** one complete behavioral paragraph describing what the feature
  does, from the user type's perspective (e.g., Super Administrator, Student).
- **Sub-features:** granular bullet list. The **last bullet is always**
  "Audit logging of the <feature>".
- **<User Type> User Journey:** numbered steps, fine-grained (screen shown,
  what is displayed, user action, system response, outcome, follow-up). The
  **last step is always** the audit-logging step.
- **Rules & Edge Cases:** bullet list covering constraints, failure modes,
  precedence, notifications, audit/compliance. The **last bullet is always** the
  audit-logging rule.
- Section labels are bold and exact: `**What it does:**`, `**Sub-features:**`,
  `**Super Administrator User Journey:**`, `**Rules & Edge Cases:**`.
- Blank line between each section block.

## 6. Test Case File Format

One test case file per feature group: `<feature_group>_tests.md`, in the same
module folder as the feature file. It must account for **every** feature,
**every** sub-feature, and **every** Rules & Edge Cases bullet of the group.

### 6.1 File Header (exact)

```markdown
# N. <Feature Group Name> — Test Cases

User Type: **<User Type>**
Source: *Mi Digital Academy - Education CRM Features Document*
Spec: <feature_group>.md — every feature, sub-feature, and rule covered

---

## Test Execution Policy
- Zero tolerance: any deviation from documented behavior = FAILED = bug
- Every bug is immediately logged/reported (Bug ID, feature, sub-feature,
  expected vs actual, severity) and fixed 100% before the group passes
- Feature group passes only at 100% test pass rate

## Coverage Matrix
| Feature | Sub-feature / Rule | Test IDs |
|---------|--------------------|----------|
| X.Y <Feature Name> | <sub-feature or rule name> | TC-<PREFIX>-<M>-<N>-<seq> |
...
```

### 6.2 Test Case Block (exact, per test)

```markdown
### TC-<PREFIX>-<M>-<N>-<seq> — <Descriptive Title>
**Type:** Positive | Negative | Edge
**Covers:** X.Y → <sub-feature or rule name>
**Preconditions:** <state required before the test>
**Steps:**
1. <fine-grained step, <User Type> perspective>
2. ...
**Expected Result:** <exact documented behavior>
**Priority:** Critical | High | Medium
```

Rules:
- Test ID scheme: `TC-<PREFIX>-<module#>-<feature group#>-<sequence>` (e.g.,
  `TC-SA-01-01-001` = Super Admin, Module 1, group 1, test 1). Unique across the
  repository. User type prefixes:

  | User type | Prefix |
  |-----------|--------|
  | Super Administrator | `TC-SA-` |
  | Student | `TC-ST-` |
  | Parent | `TC-PT-` |
  | Affiliate | `TC-AF-` |
  | Training Institute | `TC-TI-` |
- **Coverage:** every sub-feature bullet of every feature gets ≥1 positive
  (happy-path) test plus negative/edge tests where the behavior allows failure.
  Every Rules & Edge Cases bullet gets ≥1 test that deliberately triggers that
  constraint/failure mode.
- The **Coverage Matrix** must contain a row for every sub-feature and every rule,
  each mapping to at least one test ID — nothing may be skipped or left untested.
- Tests are exhaustive and behavioral (verify the feature works exactly as
  documented), never cosmetic.
- Test case blocks are grouped under `## X.Y <Feature Name>` headings matching
  the feature file.

## 7. Content Rules

- **Perspective:** the user type of the panel being documented (Super
  Administrator, Student, Parent, Affiliate, or Training Institute) performing
  the action. Always.
- **Strictly feature/function based.** The following are FORBIDDEN in content:
  - file names, folder names, directory structures
  - database types, table names, or data structures
  - implementation/technology details
- **Scope:** Phases 1–4 in scope. Mobile app in scope. Affiliate program and
  institute portal in initial build. AI features built in-house.
- **Excluded (future-ready, do NOT document):** AI Mentor Mode, virtual study
  rooms, voice notes, AR/VR, exam hall simulator, white-label/enterprise.
- Source of truth for features: the PDF features document at the repository root.

## 8. Git Rules

- After **every** file change — no matter how small — immediately:
  `git add -A` → `git commit -m "<descriptive message>"` → `git push`.
- No approval needed for these commits.
- Remote: `origin` = `https://github.com/piyushkirikaa/mi-digital-new-platform.git`,
  branch `main`.

## 9. Verification Checklist (run after any structural change)

1. Every module folder's file count matches its slim index link count and its
   `## N.` group section count.
2. Every feature file starts with the exact header (Section 5.1).
3. Every feature has all four sections in order (Section 5.2).
4. Every Sub-features list, User Journey, and Rules & Edge Cases list ends with
   its audit-logging entry.
5. No forbidden content (file names, DB structures, tech details) in any file.
6. Every feature group has a `<feature_group>_tests.md` file; its Coverage Matrix
   maps every sub-feature and rule to at least one test ID.
7. Every slim index `## Feature Documents` entry has its Test Cases link.
8. Working tree clean: committed and pushed.

## 10. Multi-User-Type Process & Autopilot Decisions

- The repository documents five user types, each with its own panel folder:
  `super_admin/`, `student/`, `parent/`, `affiliate/`, `training_institute/`.
- The process, formats, depth, content rules, git rules, and verification
  checklist are IDENTICAL for every user type. Only the perspective (User Type)
  changes.
- Build order: Super Admin (complete) → Student → Parent → Affiliate →
  Training Institute.
- Each user type's module list is derived from the PDF's own sections for that
  user type (the PDF is the source of truth).
- **Autopilot decisions:** when a genuine ambiguity is encountered during
  unattended (autopilot) work, make a documented, reasonable decision and
  continue. Every such decision is recorded in `autopilot_decisions.md` at the
  repository root with: the ambiguity, the decision, the rationale, and where it
  applies. These entries are for user review; changes are applied only after
  user review and direction.