Reorganize documentation: 72→7 root files, 11-category structure

[Copilot]

Problem

Repository root contained 72+ markdown files with no organizational structure, causing poor discoverability and maintenance burden. Multiple duplicate files (e.g., PRODUCT_REQUIREMENTS_DOCUMENT.md vs PRD.md) and inconsistent cross-references.

Changes

Structure

• Created 11-category taxonomy in docs/: getting-started/, architecture/, guides/, reference/, operations/, security/, development/, planning/, audits/, integrations/, community/
• Moved 69 files using git mv to preserve history
• Reduced root directory to 7 essential files: README.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, FAQ.md, SECURITY.md, DOCS_MIGRATION.md

Links & References

• Updated 60+ internal references across 20 files
• Fixed relative path inconsistencies throughout docs hierarchy
• Updated all .github/ configuration files (copilot-instructions, agents, prompts)

Cleanup

• Removed duplicate PRODUCT_REQUIREMENTS_DOCUMENT.md (kept docs/planning/PRD.md)
• Removed generic MANIFESTO.md (420 bytes)
• Replaced legacy docs/index.md with comprehensive docs/README.md master index

Migration

Created DOCS_MIGRATION.md documenting:

• Complete file mapping (before/after)
• Link update patterns
• Future maintenance guidance

All git history preserved. All links validated.

Original prompt

Documentation Reorganization

Problem Statement

The Krosebrook/interact repository currently has 80+ markdown documentation files scattered at the root level, making the repository extremely difficult to navigate and maintain. This creates several issues:

1. Poor discoverability - Users cannot easily find the documentation they need
2. Cluttered repository - Root directory is overwhelming with documentation files
3. Duplicate documentation - Multiple files serve similar purposes (e.g., PRD.md vs PRODUCT_REQUIREMENTS_DOCUMENT.md)
4. Inconsistent organization - No clear structure or categorization
5. Difficult maintenance - Updates are hard to track across scattered files

Objectives

Reorganize all documentation into a clear, maintainable structure that:

• Groups related documentation into logical subdirectories
• Removes or consolidates duplicate files
• Creates a master documentation index
• Keeps only essential files at root level
• Updates all internal cross-references

Proposed Structure

Root Level (Keep only these)

• README.md
• LICENSE
• CHANGELOG.md
• SECURITY.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• FAQ.md

docs/ Directory Organization

docs/
├── README.md (Master index)
├── getting-started/
│   ├── DEVELOPMENT.md
│   ├── CAPACITOR_SETUP.md
│   └── MIGRATION_QUICKSTART.md
├── architecture/
│   ├── AUTH_ARCHITECTURE.md
│   ├── DATA-FLOW.md
│   ├── STATE-MACHINE.md
│   ├── BASE44_ABSTRACTION.md
│   └── ERD.md
├── guides/
│   ├── API_INTEGRATION_GUIDE.md
│   ├── USAGE-EXAMPLES.md
│   ├── TESTING.md
│   └── CLI.md
├── reference/
│   ├── API-CONTRACTS.md
│   ├── SCHEMAS.md
│   ├── ERROR-CODES.md
│   ├── ENV-VARS.md
│   └── GLOSSARY.md
├── operations/
│   ├── DEPLOYMENT_CHECKLIST.md
│   ├── CI-CD.md
│   ├── OBSERVABILITY.md
│   ├── BACKUP-RECOVERY.md
│   └── INFRASTRUCTURE.md
├── security/
│   ├── SECURITY.md
│   ├── AUTH.md
│   ├── SSO_IMPLEMENTATION.md
│   ├── DATA-PRIVACY.md
│   ├── THREAT-MODEL.md
│   └── AUDIT-LOGS.md
├── development/
│   ├── ALGORITHMS.md
│   ├── CACHING.md
│   ├── PERFORMANCE.md
│   ├── DEPENDENCIES.md
│   └── TYPESCRIPT_MIGRATION.md
├── planning/
│   ├── PRD.md (Keep - it's the active v1.1)
│   ├── FEATURE_ROADMAP.md
│   ├── ROADMAP.md
│   └── MIGRATION_STRATEGY.md
├── audits/
│   ├── CODEBASE_AUDIT.md
│   ├── DOCUMENTATION_AUDIT_2026-01-16.md
│   ├── PRINCIPAL_AUDIT.md
│   └── BUNDLE_SIZE_REPORT.md
├── integrations/
│   ├── INTEGRATIONS.md
│   ├── MCP-SERVER.md
│   ├── VECTOR-DB.md
│   └── AGENTS.md
└── community/
    ├── AUTHORS.md
    ├── GOVERNANCE.md
    ├── SPONSORS.md
    └── ATTRIBUTION.md

Documentation to Remove/Consolidate

Remove (Duplicates/Outdated)

• PRODUCT_REQUIREMENTS_DOCUMENT.md - This is a generic template dated Jan 16, 2026 with placeholder content. The real PRD.md (v1.1, Jan 9, 2026) should be kept.
• MANIFESTO.md - Only 420 bytes, generic content, can be merged into README or removed
• BRANDING.md - Move to docs/community/ or consolidate
• TOOLS.md - Consolidate into relevant guides
• PROMPTS.md - Move to docs/guides/ or docs/development/

Consolidate

• Combine ROADMAP.md and FEATURE_ROADMAP.md into single roadmap document
• Review IMPLEMENTATION_COMPLETE.md, IMPLEMENTATION_SUMMARY.md, and REFACTOR_SUMMARY.md - likely duplicates
• Combine DOCUMENTATION_SUMMARY.md, DOCUMENTATION_GUIDELINES.md, and DOCUMENTATION_AUDIT into cohesive docs

Implementation Tasks

1. Create master docs/README.md with comprehensive navigation
2. Create all subdirectory structure in docs/
3. Move files to appropriate subdirectories (use git mv to preserve history)
4. Update internal links - scan all markdown files for ](./ or ](/ and update paths
5. Update root README.md to reference new docs structure
6. Create migration script for automated link updates
7. Remove duplicate files after consolidation
8. Add redirects or deprecation notices if needed

Files to Create

1. docs/README.md - Master documentation index with all sections
2. scripts/update-doc-links.js - Script to update internal links
3. DOCS_MIGRATION.md - Document the migration for historical reference

Link Update Pattern

When moving files, update all references from:

[Link Text](./FILENAME.md)

To:

[Link Text](./docs/category/FILENAME.md)

And update root-level references:

[Link Text](../FILENAME.md)  # from within docs/

Validation

After migration:

1. Run link checker to verify no broken links
2. Verify all files are reachable from docs/README.md
3. Ensure git history is preserved (all files should show as renamed)
4. Test that GitHub renders all links correctly

Success Criteria

• ✅ Root directory has ≤ 10 documentation files
• ✅ All documentation organized in logical subdirectories
• ✅ Master index provides clear navigation
• ✅ No broken internal links
• ✅ Duplicate files removed or consolidated
• ✅ Git hist...

This pull request was created from Copilot chat.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

---

Summary by cubic

Reorganized documentation under docs/ with a new docs/README.md hub, updated links across the repo and .github, and removed duplicates to improve navigation and maintenance. Fixed remaining relative path references across architecture, planning, reference, and security docs.

• Refactors

  • Moved files into categorized folders using git mv.
  • Added docs/README.md; removed docs/index.md.
  • Removed PRODUCT_REQUIREMENTS_DOCUMENT.md and MANIFESTO.md.
  • Updated links in README.md, CONTRIBUTING.md, FAQ.md, and .github files (agents, prompts, templates, copilot instructions).
  • Corrected relative paths across docs/* (architecture, audits, planning, reference, security).

• Migration

  • Read DOCS_MIGRATION.md for the full summary and structure.
  • Rebase branches that touched moved docs.
  • Run a link checker and fix any remaining broken links.
  • Verify all files are reachable from docs/README.md.

^{Written for commit a1e663d. Summary will update on new commits.}

[Copilot]

Pull request overview

This PR reorganizes scattered root-level documentation into a structured docs/ taxonomy, removes duplicates, and updates cross-references across the repo (including .github/ guidance) to improve discoverability and maintenance.

Changes:

• Introduced an 11-category docs/ structure with a new docs/README.md hub and removed the legacy docs/index.md.
• Added/updated multiple docs in security/reference/operations/planning/etc., plus a DOCS_MIGRATION.md mapping/guide.
• Updated internal links in root docs and GitHub agent/prompt/instructions files to reflect new paths.

Reviewed changes

Copilot reviewed 27 out of 86 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
docs/security/THREAT-MODEL.md	Updates related-doc links to new docs hierarchy.
docs/security/DATA-PRIVACY.md	Updates related-doc links to new docs hierarchy.
docs/security/AUTH.md	Adds auth/RBAC documentation.
docs/security/AUDIT-LOGS.md	Updates related-doc links to new docs hierarchy.
docs/reference/SCHEMAS.md	Fixes links to architecture docs and component schema specs.
docs/reference/ERROR-CODES.md	Adds error code reference and response format.
docs/reference/ENV-VARS.md	Updates related-doc links to new docs hierarchy.
docs/reference/API-CONTRACTS.md	Fixes links to component API reference and security auth doc.
docs/planning/SAFE_BRANCH_MERGING.md	Updates links to moved audit/recommendations docs.
docs/planning/ROADMAP.md	Updates release-history link to new community location.
docs/planning/PRE_MERGE_CHECKLIST.md	Adds a pre-merge checklist template under planning.
docs/planning/PRD_GENERATOR_GUIDE.md	Adds usage guide for PRD generator tooling.
docs/planning/MIGRATION_STRATEGY.md	Updates references to ADRs/security/operations docs.
docs/planning/MIGRATION.md	Adds placeholder migration doc under planning.
docs/planning/EXECUTIVE_SUMMARY.md	Adds modernization initiative executive summary.
docs/operations/OBSERVABILITY.md	Adds placeholder observability doc under operations.
docs/operations/INFRASTRUCTURE.md	Adds infrastructure overview under operations.
docs/operations/CI-CD.md	Adds CI/CD doc under operations (includes workflow snippet).
docs/operations/BACKUP-RECOVERY.md	Adds placeholder backup/recovery doc under operations.
docs/integrations/VECTOR-DB.md	Adds placeholder vector DB integration doc.
docs/integrations/AGENTS.md	Adds/relocates agents documentation under integrations.
docs/index.md	Removes legacy docs index (replaced by docs/README.md).
docs/guides/CLI.md	Adds CLI reference under guides.
docs/getting-started/MIGRATION_QUICKSTART.md	Adds quickstart for modernization initiative.
docs/getting-started/DEVELOPMENT.md	Adds development guide under getting-started.
docs/getting-started/CAPACITOR_SETUP.md	Adds Capacitor Android setup guide under getting-started.
docs/development/TOOLS.md	Adds tools catalog under development.
docs/development/PERFORMANCE.md	Adds performance targets/strategies under development.
docs/development/DEPENDENCIES.md	Adds dependency inventory/policy under development.
docs/development/CACHING.md	Adds caching strategy doc under development.
docs/development/AI-SAFETY.md	Adds AI safety guidelines under development.
docs/community/SUPPORT.md	Adds support channels/resources under community.
docs/community/SPONSORS.md	Adds sponsors placeholder under community.
docs/community/RELEASES.md	Adds release management doc under community.
docs/community/GOVERNANCE.md	Adds governance model under community.
docs/community/BRANDING.md	Adds brand guidelines under community.
docs/community/AUTHORS.md	Adds contributors/recognition doc under community.
docs/community/ATTRIBUTION.md	Adds attribution/licensing acknowledgments under community.
docs/audits/REFACTOR_SUMMARY.md	Moves/adds refactor summary under audits.
docs/audits/MERGE_IMPLEMENTATION_SUMMARY.md	Moves/adds merge implementation summary under audits.
docs/audits/IMPLEMENTATION_SUMMARY.md	Moves/adds implementation summary under audits.
docs/audits/IMPLEMENTATION_COMPLETE.md	Moves/adds implementation completion summary under audits.
docs/audits/BUNDLE_SIZE_REPORT.md	Moves/adds bundle size report under audits.
docs/audits/BASE44_MIGRATION_AUDIT.md	Updates ADR link path to new relative location.
docs/architecture/STATE-MACHINE.md	Adds state machine doc under architecture.
docs/architecture/ERD.md	Adds ERD doc under architecture.
docs/architecture/DATA-FLOW.md	Adds data-flow doc under architecture.
docs/architecture/ARCHITECTURE_OVERVIEW.md	Updates data-flow link to new in-folder architecture doc.
docs/README.md	Adds master docs hub index for the new taxonomy.
README.md	Updates key documentation links to new docs structure.
MANIFESTO.md	Removes duplicate/generic manifesto doc.
FAQ.md	Updates links to the new docs structure.
DOCS_MIGRATION.md	Adds migration mapping, link update patterns, and maintenance guidance.
CONTRIBUTING.md	Updates links to moved testing/audits/roadmap docs.
.github/prompts/agent-typescript-migration.md	Updates PRD reference path.
.github/prompts/agent-cognitive-loop.md	Updates PRD reference path.
.github/prompts/agent-ai-recommendations.md	Updates PRD reference path.
.github/copilot-instructions.md	Updates references to moved planning/audit docs.
.github/base44-updates.md	Updates PRD/roadmap references to new docs paths.
.github/agents/documentation-writer.agent.md	Updates example directory structure and doc references.
.github/agents.md	Updates PRD/roadmap references to new docs paths.
.github/FEATURE_TO_PR_TEMPLATE.md	Updates CODEBASE_AUDIT/PRD/roadmap reference paths.

[Krosebrook]

@copilot apply changes based on the comments in this thread

[cubic-dev-ai]

4 issues found across 86 files

Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name=".github/agents/documentation-writer.agent.md">

<violation number="1" location=".github/agents/documentation-writer.agent.md:23">
P3: The updated directory tree now implies `security/`, `api/`, and `guides/` are children of `CONTRIBUTING.md` because the old subtree lines were left in place. Update the tree so these directories are properly nested under `docs/` (or removed if they no longer exist) to avoid misleading structure.</violation>
</file>

<file name="DOCS_MIGRATION.md">

<violation number="1" location="DOCS_MIGRATION.md:15">
P3: The root file count is off by one; DOCS_MIGRATION.md itself lives at the repo root, so the cleanup should reflect 7 files instead of 6.</violation>

<violation number="2" location="DOCS_MIGRATION.md:91">
P3: The planning section count is incorrect; it lists 11 files but claims 10.</violation>

<violation number="3" location="DOCS_MIGRATION.md:103">
P3: The audits section count is incorrect; it lists 10 files but claims 9.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P3: The updated directory tree now implies security/, api/, and guides/ are children of CONTRIBUTING.md because the old subtree lines were left in place. Update the tree so these directories are properly nested under docs/ (or removed if they no longer exist) to avoid misleading structure.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At .github/agents/documentation-writer.agent.md, line 23:

<comment>The updated directory tree now implies `security/`, `api/`, and `guides/` are children of `CONTRIBUTING.md` because the old subtree lines were left in place. Update the tree so these directories are properly nested under `docs/` (or removed if they no longer exist) to avoid misleading structure.</comment>

<file context>
@@ -20,14 +20,18 @@ The Interact platform has extensive documentation with a score of **98/100** (as
-├── FEATURE_ROADMAP.md          # 18-month roadmap
-├── TESTING.md                   # Testing guide
-├── CODEBASE_AUDIT.md           # Technical audit
+├── docs/
+│   ├── README.md               # Documentation hub
+│   ├── planning/
</file context>

[cubic-dev-ai]

P3: The audits section count is incorrect; it lists 10 files but claims 9.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At DOCS_MIGRATION.md, line 103:

<comment>The audits section count is incorrect; it lists 10 files but claims 9.</comment>

<file context>
@@ -0,0 +1,308 @@
+│   ├── RECOMMENDATIONS.md
+│   ├── ROADMAP.md
+│   └── SAFE_BRANCH_MERGING.md
+├── audits/                     # 9 files
+│   ├── BASE44_MIGRATION_AUDIT.md
+│   ├── BUNDLE_SIZE_REPORT.md
</file context>

[cubic-dev-ai]

P3: The planning section count is incorrect; it lists 11 files but claims 10.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At DOCS_MIGRATION.md, line 91:

<comment>The planning section count is incorrect; it lists 11 files but claims 10.</comment>

<file context>
@@ -0,0 +1,308 @@
+│   ├── PROMPTS.md
+│   ├── TOOLS.md
+│   └── TYPESCRIPT_MIGRATION.md
+├── planning/                   # 10 files
+│   ├── BRANCH_MERGING_PLAN.md
+│   ├── EXECUTIVE_SUMMARY.md
</file context>

[cubic-dev-ai]

P3: The root file count is off by one; DOCS_MIGRATION.md itself lives at the repo root, so the cleanup should reflect 7 files instead of 6.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At DOCS_MIGRATION.md, line 15:

<comment>The root file count is off by one; DOCS_MIGRATION.md itself lives at the repo root, so the cleanup should reflect 7 files instead of 6.</comment>

<file context>
@@ -0,0 +1,308 @@
+
+## Goals Achieved
+
+✅ **Root directory cleanup:** 72 → 6 files (Target: ≤10)  
+✅ **Organized structure:** 11 logical categories  
+✅ **Git history preserved:** All files moved with `git mv`  
</file context>