================================================================================
COLLABTUNES FOLDER AND PACKAGE AUTHORITY STRUCTURE
Version: 1.0 | Date: 5_13_26 | Status: AUTHORITATIVE
Owner: Mixed Claude / Tom
Purpose: Definitive reference for folder roles, authority layers,
         naming conventions, and ZIP checkpoint standards.
================================================================================

================================================================================
SECTION 1 — PROJECT ROOT FOLDER MAP
================================================================================

COLLABTUNES_PROJECT_ROOT/
│
├── 00_OPERATIONAL_RULES/       AUTHORITY LAYER: LOCKED
│   Purpose: Permanent operational doctrine. Never overwritten.
│   Contains: naming standards, stabilization rules, deployment doctrine
│   Write access: Tom only
│   File types: TXT, PDF
│   Naming: COLLABTUNES_{TOPIC}_RULES_{DATE}.txt
│
├── 01_LIVE_CAPTURE/            AUTHORITY LAYER: REFERENCE
│   Purpose: HTML/TXT snapshots from live site (SGC-1 outputs)
│   Contains: live site snapshots, page captures, manifest exports
│   Write access: SGC-1 output only
│   File types: HTML, TXT, JSON
│   Naming: SGC1_LIVE_SITE_SNAPSHOT_{run_id}.json
│            COLLABTUNES_{PAGE_NAME}_LIVE_CAPTURE_{DATE}.html
│
├── 02_CANON/                   AUTHORITY LAYER: LOCKED / AUTHORITATIVE
│   Purpose: All authority registry and canon documents
│   Contains: MASTER_URL_AUTHORITY_REGISTRY, FINAL_CANON_AUTHORITY_REGISTRY,
│             FINAL_NAVIGATION_AUTHORITY_MAP
│   Write access: Tom-reviewed changes only
│   File types: TXT
│   Naming: {DOCUMENT_NAME}_VOL{N}_{DATE}.txt
│            Final version: {DOCUMENT_NAME}_ACTIVE_CANON_{DATE}.txt
│
├── 03_RATINGS/                 AUTHORITY LAYER: AUTHORITATIVE
│   Purpose: Content rating records for all 34 collections
│   Contains: MASTER_CONTENT_RATINGS_INDEX, per-collection rating files
│   Write access: Tom-reviewed changes only
│   File types: TXT
│   Naming: MASTER_CONTENT_RATINGS_INDEX_VOL{N}_{DATE}.txt
│
├── 04_BLOCKERS/                AUTHORITY LAYER: WORKING
│   Purpose: Blocker registry and conflict tracking
│   Contains: BLOCKER_REGISTRY, per-blocker resolution notes
│   Write access: Any authorized team member
│   File types: TXT
│   Naming: COLLABTUNES_BLOCKER_REGISTRY_{DATE}.txt
│            BLOCKER_{ID}_RESOLUTION_NOTES_{DATE}.txt
│
├── 05_URL_MAPS/                AUTHORITY LAYER: AUTHORITATIVE
│   Purpose: URL mapping, slug registry, redirect tables
│   Contains: MASTER_URL_AUTHORITY_REGISTRY, redirect maps
│   Write access: SGC-1 output + Tom review
│   File types: TXT, JSON
│   Naming: MASTER_URL_AUTHORITY_REGISTRY_VOL{N}_{DATE}.txt
│
├── 06_NAV_STABILIZATION/       AUTHORITY LAYER: AUTHORITATIVE
│   Purpose: Navigation audit results and nav authority map
│   Contains: FINAL_NAVIGATION_AUTHORITY_MAP, nav QA reports
│   Write access: Tom-reviewed changes only
│   File types: TXT
│   Naming: FINAL_NAVIGATION_AUTHORITY_MAP_{DATE}.txt
│            COLLABTUNES_NAVIGATION_QA_REPORT_{DATE}.txt
│
├── 07_DEPLOYMENT/              AUTHORITY LAYER: WORKING → LOCKED on deploy
│   Purpose: Deployment packages, handoff docs, rollback plans
│   Contains: deployment ZIPs, handoff checklists, rollback ZIPs
│   Write access: Deployment pipeline only
│   File types: ZIP, TXT
│   Naming: COLLABTUNES_DEPLOYMENT_PACKAGE_{VERSION}_{DATE}.zip
│            COLLABTUNES_ROLLBACK_{VERSION}_{DATE}.zip
│
├── 08_PLACEHOLDERS/            AUTHORITY LAYER: WORKING
│   Purpose: Coming-soon and placeholder page definitions
│   Contains: placeholder page specs, future page planning
│   Write access: Tom
│   File types: TXT, HTML
│   Naming: COLLABTUNES_PLACEHOLDER_{PAGE_NAME}_{DATE}.txt
│
├── 09_HTML_PROTOTYPES/         AUTHORITY LAYER: WORKING
│   Purpose: HTML prototypes and tester pages
│   Contains: HTML_TESTER files, AIO prototypes, nav prototypes
│   Write access: Developer
│   File types: HTML
│   Naming: COLLABTUNES_{COMPONENT}_PROTOTYPE_{DATE}.html
│            HTML_TESTER_{NUMBER}_{DESCRIPTION}_{DATE}.html
│            {FILE}_FIXED_COLOR_{DATE}.html    ← color-corrected versions
│
├── 10_QA/                      AUTHORITY LAYER: REFERENCE
│   Purpose: QA reports, audit outputs, test results
│   Contains: deployment readiness audits, nav QA, rating QA
│   Write access: QA tools (SGC output) + auditor
│   File types: TXT, JSON
│   Naming: COLLABTUNES_DEPLOYMENT_AUDIT_{CYCLE_ID}_{DATE}.txt
│            COLLABTUNES_{SUBSYSTEM}_QA_REPORT_{DATE}.txt
│
├── 11_REGISTRY/                AUTHORITY LAYER: AUTHORITATIVE
│   Purpose: Machine-readable registries for all subsystems
│   Contains: title registries, collection registries, anchor registries
│   Write access: Generator output + Tom review
│   File types: TXT, JSON
│   Naming: COLLABTUNES_{SUBSYSTEM}_REGISTRY_VOL{N}_{DATE}.txt
│
├── 12_MANIFESTS/               AUTHORITY LAYER: AUTHORITATIVE
│   Purpose: ZIP manifests and package inventories
│   Contains: manifests for all major ZIPs and packages
│   Write access: Packaging pipeline
│   File types: TXT
│   Naming: MANIFEST_{PACKAGE_NAME}_{DATE}.txt
│            ZIP_MANIFEST_{ZIP_NAME}_{DATE}.txt
│
├── 13_SOURCE_ZIPS/             AUTHORITY LAYER: REFERENCE / ARCHIVE
│   Purpose: Source archive ZIPs organized by date
│   Contains: stabilization checkpoint ZIPs, session packages
│   Write access: Packaging pipeline
│   File types: ZIP
│   Naming: {N}_ZIP_{DESCRIPTION}_{DATE}.zip
│            (N = file count, always included)
│
├── 14_GENERATED_OUTPUT/        AUTHORITY LAYER: WORKING
│   Purpose: Generator outputs ONLY. Never manually edited.
│   Contains: AIO page exports, registry exports, nav exports
│   Write access: Generator pipeline only
│   File types: HTML, TXT, JSON
│   Naming: GENERATED_{COMPONENT}_{COLLECTION_ID}_{DATE}.html
│            GENERATED_{COMPONENT}_{run_id}.json
│   RULE: If you manually edited a file in this folder,
│         move it to the appropriate canon folder immediately.
│
└── 15_GATHERING_TOOLS/         AUTHORITY LAYER: AUTHORITATIVE
    Purpose: SGC-1, SGC-2, shared modules, test suite
    Contains: All Self-Gathering Code
    Write access: Developers only (never write here during site operations)
    File types: PY
    Naming: sgc{N}_{module_name}.py
             shared_{module_name}.py

================================================================================
SECTION 2 — AUTHORITY LAYER DEFINITIONS
================================================================================

LOCKED
  Definition: Finalized, approved, canonical. Cannot be changed without
              explicit Tom sign-off. Generator reads these; never overwrites them.
  Files in this layer: ACTIVE_CANON files, operational doctrine
  Color code: 🔴 (if using visual tracking)

AUTHORITATIVE
  Definition: Current best version. Supersedes all prior versions.
              Highest VOL number = AUTHORITATIVE by default.
  Files in this layer: Registry VOL files, nav maps, ratings indexes
  Color code: 🟠

REFERENCE
  Definition: Prior version retained for historical context.
              Superseded by AUTHORITATIVE version.
              Do not use for generation — read-only archive.
  Files in this layer: Old VOL files, superseded registries
  Color code: 🟡

WORKING
  Definition: Active draft. Not yet stable. Do not use for generation.
  Files in this layer: Drafts, experiments, in-progress QA
  Color code: 🟢

DEPRECATED
  Definition: Intentionally retired. Retained for audit trail only.
              Never use for anything. Move to archive if space permits.
  Files in this layer: Replaced files, failed experiments
  Color code: ⚫

CONFLICT
  Definition: Two files claim the same authority. Unresolved.
              Neither should be used for generation until resolved.
  Files in this layer: Files with AMBIGUOUS_VERSION flag
  Color code: 🔵 (needs attention)

================================================================================
SECTION 3 — ZIP CHECKPOINT STANDARDS
================================================================================

WHEN TO CREATE A ZIP CHECKPOINT:
1. Before any major operation (pre-flight backup)
2. After any stabilization cycle completion
3. After any canon update
4. After any deployment package creation
5. At the end of every session that modifies canon files

ZIP NAMING STANDARD:
{FILE_COUNT}_{FILE_TYPES}_{DESCRIPTION}_{DATE}.zip

Components:
  FILE_COUNT:  Integer count of files inside the ZIP
  FILE_TYPES:  Comma-separated type tokens (TXT, ZIP, HTML, PY, JSON)
  DESCRIPTION: UPPERCASE, underscore-separated, describes contents
  DATE:        M_D_YY format (e.g. 5_13_26)

Examples:
  43_PY_TXT_ZIP_SGC1_STAGE2_LIVE_SITE_NAV_ROUTING_GATHERER_PACKAGE_5_13_26.zip
  11_TXT_COLLABTUNES_CANON_STABILIZATION_CHECKPOINT_5_13_26.zip
  6_HTML_TXT_COLLABTUNES_AIO_PROTOTYPE_BATCH_1_5_13_26.zip

BANNED ZIP NAMES (never use):
  final.zip
  backup.zip
  new_version.zip
  fixed.zip
  archive2.zip
  temp_package.zip

MANIFEST REQUIREMENT:
Every ZIP must have a manifest file inside it named:
  ZIP_MANIFEST_{DESCRIPTION}_{DATE}.txt

Manifest must contain:
  ZIP_NAME:       (the zip filename)
  CREATED:        (date)
  PHASE:          (what phase this ZIP belongs to)
  CATEGORY:       (from APPROVED_CATEGORIES list)
  AUTHORITATIVE:  (YES / NO)
  CONTAINS:
    - {member_filename_1}
    - {member_filename_2}
    ...

================================================================================
SECTION 4 — STAGING VS PRODUCTION SEPARATION
================================================================================

STAGING FOLDERS (work-in-progress, not deployment-ready):
  09_HTML_PROTOTYPES/   ← prototypes being tested
  14_GENERATED_OUTPUT/  ← generator output before review
  10_QA/                ← active QA work

PRODUCTION FOLDERS (stable, reviewed, deployment-ready):
  02_CANON/             ← locked authority documents
  03_RATINGS/           ← verified ratings
  05_URL_MAPS/          ← verified URL registry
  06_NAV_STABILIZATION/ ← verified nav map
  07_DEPLOYMENT/        ← deployment packages

ARCHIVE FOLDERS (historical reference only):
  13_SOURCE_ZIPS/       ← session archives
  12_MANIFESTS/         ← package manifests

SEPARATION RULES:
1. Never move a file from staging to production without review.
2. Never edit a production file without creating a new VOL.
3. Never use a staging file as input for the generator.
4. When in doubt: staging, not production.

================================================================================
SECTION 5 — VERSION CONTROL DISCIPLINE
================================================================================

CREATING A NEW VERSION:
1. Never overwrite existing files.
2. Increment VOL number: VOL1 → VOL2 → VOL3
3. New file gets new date stamp.
4. Old file gets REFERENCE or DEPRECATED designation.
5. Old file stays in folder (audit trail).

SUPERSEDING A FILE:
1. New file's header must include: SUPERSEDES: {old_filename}
2. Old file's header should be annotated: SUPERSEDED_BY: {new_filename}
3. SGC-2 will auto-detect this via supersedes_refs scan.

RESOLVING AN AMBIGUOUS_VERSION FLAG:
1. Identify which file is the true current version.
2. Higher VOL number wins if equal date.
3. Later date wins if equal VOL.
4. If genuinely ambiguous: Tom decides, documents decision, creates new VOL.

================================================================================
END COLLABTUNES FOLDER AND PACKAGE AUTHORITY STRUCTURE
================================================================================
