Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Krosebrook merged 6 commits into from
Feb 12, 2026
+649 −1,984
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
cac3097
Initial plan
Copilot Feb 10, 2026
9b5d2dc
Move 47 documentation files into organized docs/ structure
Copilot Feb 10, 2026
3526f8b
Move remaining docs, remove duplicates, organize existing docs/ files
Copilot Feb 10, 2026
043e2a3
Update all internal documentation links to reflect new structure
Copilot Feb 10, 2026
64ff622
Update all .github references to new docs structure and add migration…
Copilot Feb 10, 2026
a1e663d
Fix relative path references in documentation files
Copilot Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions .github/FEATURE_TO_PR_TEMPLATE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -459,7 +459,7 @@ npm run dev
**Known Constraints**:
- ⚠️ **No tests yet**: Testing infrastructure needs to be added (Vitest planned)
- ⚠️ **JavaScript only**: No TypeScript (migration planned for Q2 2025)
- ⚠️ **8 security vulnerabilities**: Documented in CODEBASE_AUDIT.md
- ⚠️ **8 security vulnerabilities**: Documented in docs/audits/CODEBASE_AUDIT.md
- ⚠️ **100+ ESLint warnings**: Ongoing cleanup

**Build Commands**:
Expand All @@ -473,9 +473,9 @@ npm run preview # Preview production build

**Required Reading** (check these first):
- `.github/copilot-instructions.md` - Coding standards and patterns
- `CODEBASE_AUDIT.md` - Security findings and known issues
- `PRD.md` - Product requirements document
- `FEATURE_ROADMAP.md` - Planned features and timeline
- `docs/audits/CODEBASE_AUDIT.md` - Security findings and known issues
- `docs/planning/PRD.md` - Product requirements document
- `docs/planning/FEATURE_ROADMAP.md` - Planned features and timeline

**Helpful Context**:
- 47 application pages
Expand Down Expand Up @@ -568,7 +568,7 @@ Acceptance Criteria:
## 📞 Need Help?

If stuck or unsure:
1. **Check documentation**: README, CODEBASE_AUDIT.md, PRD.md
1. **Check documentation**: README, docs/audits/CODEBASE_AUDIT.md, docs/planning/PRD.md
2. **Look for similar code**: Find reference implementation
3. **Ask specific questions**: "Should I use pattern A or B?" not "What should I do?"
4. **Propose a solution**: "I'm planning X because Y. Thoughts?" gets faster feedback
Expand Down
6 changes: 3 additions & 3 deletions .github/agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -115,7 +115,7 @@ src/modules/

- `.github/base44-updates.md` - Detailed implementation guide
- `README.md` - Updated project structure section
- `PRD.md` - Architecture section
- `docs/planning/PRD.md` - Architecture section

---

Expand Down Expand Up @@ -657,8 +657,8 @@ When working on this codebase:
- **.github/copilot-instructions.md** - Coding standards and patterns
- **.github/base44-updates.md** - Base44 integration guide
- **This file (agents.md)** - Historical context and decisions
- **PRD.md** - Product requirements and architecture
- **FEATURE_ROADMAP.md** - Planned features and priorities
- **docs/planning/PRD.md** - Product requirements and architecture
- **docs/planning/FEATURE_ROADMAP.md** - Planned features and priorities

#### 2. Follow the Module Pattern for New Features

Expand Down
32 changes: 20 additions & 12 deletions .github/agents/documentation-writer.agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,18 @@ The Interact platform has extensive documentation with a score of **98/100** (as
```
/
├── README.md # Main project readme
├── AGENTS.md # Agent documentation
├── PRD.md # Product requirements
├── FEATURE_ROADMAP.md # 18-month roadmap
├── TESTING.md # Testing guide
├── CODEBASE_AUDIT.md # Technical audit
├── docs/
Copy link

@cubic-dev-ai cubic-dev-ai bot Feb 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Fix with Cubic

│ ├── README.md # Documentation hub
│ ├── planning/
│ │ ├── PRD.md # Product requirements
│ │ └── FEATURE_ROADMAP.md # 18-month roadmap
│ ├── guides/
│ │ └── TESTING.md # Testing guide
│ ├── audits/
│ │ └── CODEBASE_AUDIT.md # Technical audit
│ └── integrations/
│ └── AGENTS.md # Agent documentation
├── CONTRIBUTING.md # Contribution guidelines
├── docs/ # Documentation directory
│ ├── index.md # Documentation hub
│ ├── security/ # Security docs
│ ├── api/ # API documentation
│ └── guides/ # How-to guides
Expand Down Expand Up @@ -439,19 +443,23 @@ When writing documentation:
Check these existing docs for patterns:
- `README.md` - High-level overview, badges, quick start
- `TESTING.md` - Comprehensive technical guide
- `API_INTEGRATION_GUIDE.md` - API documentation
- `docs/guides/API_INTEGRATION_GUIDE.md` - API documentation
- `CONTRIBUTING.md` - Process documentation
- `FEATURE_ROADMAP.md` - Roadmap format
- `docs/planning/FEATURE_ROADMAP.md` - Roadmap format

## Documentation Locations

### Root-level docs
Major docs go in project root:
Essential docs at project root:
- `README.md` - Main entry point
- `PRD.md` - Product requirements
- `TESTING.md` - Testing guide
- `CONTRIBUTING.md` - How to contribute
- `SECURITY.md` - Security guidelines

### Organized docs/
All other docs in organized structure:
- `docs/planning/PRD.md` - Product requirements
- `docs/guides/TESTING.md` - Testing guide

### Component docs
Component-specific docs in `components/docs/`:
- Architecture overviews
Expand Down
4 changes: 2 additions & 2 deletions .github/base44-updates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -767,8 +767,8 @@ Verify component appears and functions in Base44 canvas.

### Interact Documentation
- **README.md** - Quick start and overview
- **PRD.md** - Product requirements and architecture
- **FEATURE_ROADMAP.md** - 18-month feature roadmap
- **docs/planning/PRD.md** - Product requirements and architecture
- **docs/planning/FEATURE_ROADMAP.md** - 18-month feature roadmap
- **CODEBASE_AUDIT.md** - Security and quality metrics
- **.github/agents.md** - AI agent context log (for future reference)

Expand Down
20 changes: 10 additions & 10 deletions .github/copilot-instructions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -207,11 +207,11 @@ try {
```

## Documentation References
- **CODEBASE_AUDIT.md** - Security vulnerabilities and code quality issues
- **PRD.md** - Product requirements and technical architecture
- **FEATURE_ROADMAP.md** - 18-month roadmap with 15 features
- **DOCUMENTATION_SUMMARY.md** - Overview of all documentation
- **RECOMMENDATIONS.md** - Best practices and repository recommendations
- **docs/audits/CODEBASE_AUDIT.md** - Security vulnerabilities and code quality issues
- **docs/planning/PRD.md** - Product requirements and technical architecture
- **docs/planning/FEATURE_ROADMAP.md** - 18-month roadmap with 15 features
- **docs/audits/DOCUMENTATION_SUMMARY.md** - Overview of all documentation
- **docs/planning/RECOMMENDATIONS.md** - Best practices and repository recommendations

## Git Workflow
- Branch naming: `feature/feature-name` or `fix/bug-name`
Expand All @@ -226,9 +226,9 @@ try {
## When Working on Code

### Before Making Changes
1. Check CODEBASE_AUDIT.md for known issues in the area
2. Review PRD.md for requirements and constraints
3. Check FEATURE_ROADMAP.md for related features
1. Check docs/audits/CODEBASE_AUDIT.md for known issues in the area
2. Review docs/planning/PRD.md for requirements and constraints
3. Check docs/planning/FEATURE_ROADMAP.md for related features
4. Ensure tests exist (or create them)

### While Coding
Expand Down Expand Up @@ -259,8 +259,8 @@ try {

## Questions or Clarifications
For ambiguous requirements, refer to:
1. PRD.md (product requirements)
2. FEATURE_ROADMAP.md (implementation details)
1. docs/planning/PRD.md (product requirements)
2. docs/planning/FEATURE_ROADMAP.md (implementation details)
3. Existing similar implementations in codebase
4. Team lead or product owner

Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/agent-ai-recommendations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ You are an AI/ML engineer specializing in recommendation systems. Build Feature
- functions/ (Base44 backend functions)
- src/api/ (API client configuration)
- FEATURE_ROADMAP.md (Feature 4: AI Recommendation Engine)
- PRD.md (AI integration requirements)
- docs/planning/PRD.md (AI integration requirements)

## AI Service Environment Variables Required
- OPENAI_API_KEY
Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/agent-cognitive-loop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -412,7 +412,7 @@ LOOP_DECISION: CONTINUE → await clarification
## Files to Reference
- FEATURE_ROADMAP.md (planned features and timeline)
- CODEBASE_AUDIT.md (security and quality issues)
- PRD.md (product requirements)
- docs/planning/PRD.md (product requirements)
- RECOMMENDATIONS.md (best practices)
- .github/copilot-instructions.md (coding standards)

Expand Down
2 changes: 1 addition & 1 deletion .github/prompts/agent-typescript-migration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,4 +50,4 @@ You are a TypeScript migration specialist. Execute Phase 1 migration:
## Files to Reference
- jsconfig.json (current configuration)
- FEATURE_ROADMAP.md (Feature 3: TypeScript Migration)
- PRD.md (Technical Architecture section)
- docs/planning/PRD.md (Technical Architecture section)
22 changes: 11 additions & 11 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,7 +471,7 @@ npm test -- path/to/test.js
npm test -- --coverage
```

**See [TESTING.md](./TESTING.md) for detailed testing guidelines.**
**See [TESTING.md](./docs/guides/TESTING.md) for detailed testing guidelines.**

---

Expand Down Expand Up @@ -554,10 +554,10 @@ npm audit

### Resources

- **Documentation:** Start with [README.md](./README.md) and [DOCUMENTATION_SUMMARY.md](./DOCUMENTATION_SUMMARY.md)
- **Codebase Audit:** See [CODEBASE_AUDIT.md](./CODEBASE_AUDIT.md) for architecture
- **Feature Roadmap:** Check [FEATURE_ROADMAP.md](./FEATURE_ROADMAP.md) for planned features
- **Testing Guide:** Read [TESTING.md](./TESTING.md) for testing standards
- **Documentation:** Start with [README.md](./README.md) and [DOCUMENTATION_SUMMARY.md](./docs/audits/DOCUMENTATION_SUMMARY.md)
- **Codebase Audit:** See [CODEBASE_AUDIT.md](./docs/audits/CODEBASE_AUDIT.md) for architecture
- **Feature Roadmap:** Check [FEATURE_ROADMAP.md](./docs/planning/FEATURE_ROADMAP.md) for planned features
- **Testing Guide:** Read [TESTING.md](./docs/guides/TESTING.md) for testing standards

### Communication Channels

Expand All @@ -570,16 +570,16 @@ npm audit
### Common Questions

**Q: How do I set up Base44 SDK?**
A: See [API_INTEGRATION_GUIDE.md](./API_INTEGRATION_GUIDE.md) for setup instructions.
A: See [API_INTEGRATION_GUIDE.md](./docs/guides/API_INTEGRATION_GUIDE.md) for setup instructions.

**Q: What's the testing strategy?**
A: See [TESTING.md](./TESTING.md) for comprehensive testing guidelines.
A: See [TESTING.md](./docs/guides/TESTING.md) for comprehensive testing guidelines.

**Q: How do I run the linter?**
A: Run `npm run lint` to check, `npm run lint:fix` to auto-fix.

**Q: My PR has merge conflicts, what do I do?**
A: See [docs/SAFE_BRANCH_MERGING.md](./docs/SAFE_BRANCH_MERGING.md) for safe merging practices.
A: See [docs/SAFE_BRANCH_MERGING.md](./docs/planning/SAFE_BRANCH_MERGING.md) for safe merging practices.

---

Expand Down Expand Up @@ -652,9 +652,9 @@ Thank you for contributing to Interact! 🎉

**Related Documentation:**
- [README.md](./README.md) - Project overview
- [TESTING.md](./TESTING.md) - Testing guidelines
- [CODEBASE_AUDIT.md](./CODEBASE_AUDIT.md) - Code quality standards
- [FEATURE_ROADMAP.md](./FEATURE_ROADMAP.md) - Feature planning
- [TESTING.md](./docs/guides/TESTING.md) - Testing guidelines
- [CODEBASE_AUDIT.md](./docs/audits/CODEBASE_AUDIT.md) - Code quality standards
- [FEATURE_ROADMAP.md](./docs/planning/FEATURE_ROADMAP.md) - Feature planning

---

Expand Down
Loading
Loading