personamanagmentlayer__pcl/docs/ORGANIZATION.md

PCL Documentation Organization

Last Updated: 2026-01-19

---

Overview

This document describes the organization of PCL documentation to make it easy to find what you need.

---

Root Directory

The root directory contains only essential project files:

File	Purpose
README.md	Project overview and quick start
CHANGELOG.md	Version history and changes
CONTRIBUTING.md	How to contribute to PCL
SECURITY.md	Security policy and vulnerability reporting
LICENSE	Apache 2.0 license
package.json	NPM package configuration
.gitignore	Git ignore rules
.editorconfig	Editor configuration
.prettierrc	Code formatting rules
.eslintrc.json	Linting configuration

All other documentation is organized in the docs/ directory.

---

Documentation Structure

docs/
├── INDEX.md                    # Main documentation index (START HERE!)
├── ORGANIZATION.md             # This file
│
├── phases/                     # Phase completion documents
│   ├── PHASE-2.4-COMPLETE.md
│   ├── PHASE-2.5-2.7-PLAN.md
│   ├── PHASE-2.5-2.7-PROGRESS.md
│   ├── PHASE-2-COMPLETE.md
│   ├── PHASE-2-VALIDATION.md
│   └── SKILLS-CLI-COMPLETE.md
│
├── quickref/                   # Quick reference guides
│   ├── QUICKSTART.md
│   ├── BUILD-QUICK-REF.md
│   └── SKILLS-CLI-QUICK-REF.md
│
├── sessions/                   # Session summaries
│   ├── SESSION-2026-01-18-FINAL.md
│   └── SESSION-SUMMARY-DETAILED.md
│
├── guides/                     # User guides and tutorials
│   ├── GETTING-STARTED.md
│   ├── GETTING-STARTED-CURRENT.md
│   ├── EVENT-SYSTEM.md
│   ├── REGISTRY-USAGE.md
│   └── ...
│
├── api/                        # API reference documentation
│   ├── PARSER.md
│   ├── SEMANTIC.md
│   ├── CODEGEN.md
│   ├── REGISTRY-ARCHITECTURE.md
│   └── ...
│
├── skills/                     # Skills ecosystem docs
│   ├── CLAUDE-CODE-COMPATIBILITY.md
│   ├── AGENT-SKILLS-COMPATIBILITY.md
│   └── CLI-USAGE.md
│
├── registry/                   # Registry system docs
│   ├── REGISTRY-CHEATSHEET.md
│   ├── DATABASE-FREE-REGISTRY.md
│   └── TEST-RESULTS.md
│
├── reference/                  # Language reference
│   ├── LANGUAGE.md
│   ├── SYNTAX.md
│   └── ERROR-CODES.md
│
└── changelog/                  # Detailed changelogs
    └── CHANGELOG-2026-01-18.md

---

Finding What You Need

I'm New to PCL

Start here in order:

1. Root README - Project overview
2. Quickstart Guide - Get started in 5 minutes
3. Getting Started Guide - Full tutorial
4. Documentation Index - Browse all documentation

I Want to Build Something

Build system resources:

1. Build Quick Reference - Commands overview
2. Build System Guide - Complete guide
3. Phase 2.4 Complete - Build system details

I Want to Use Skills

Skills resources:

1. Skills CLI Quick Reference - Commands overview
2. Skills CLI Usage - Complete guide
3. Claude Code Compatibility - Claude Code integration
4. Agent Skills Compatibility - agentskills.io integration

I'm Using an IDE

IDE integration:

1. VSCode Setup - VSCode extension setup
2. Phase 2.1 Complete - LSP features
3. Phase 2.5-2.7 Plan - JetBrains/Neovim plans

I Need API Documentation

API references:

1. Parser API - Parsing PCL code
2. Semantic API - Type checking
3. Codegen API - Code generation
4. Registry API - Registry system

I Want to Contribute

Contributing resources:

1. Contributing Guide - How to contribute
2. Project Structure - Codebase organization
3. Phase Documentation - Current development status

I Found a Security Issue

Security resources:

1. Security Policy - Vulnerability reporting
2. Security Hardening - Best practices
3. Security Bootstrap - Security setup

---

Documentation Categories

1. Quick References (quickref/)

Fast, actionable guides:

• Command syntax
• Common patterns
• Cheat sheets
• Quick examples

Best for: Daily development, looking up commands

2. Guides (guides/)

Step-by-step tutorials:

• Getting started
• Feature deep-dives
• Best practices
• Integration guides

Best for: Learning, onboarding, understanding features

3. API Documentation (api/)

Technical reference:

• Function signatures
• Class interfaces
• Return types
• Usage examples

Best for: Programming, integration, automation

4. Phase Documents (phases/)

Development tracking:

• Feature completion
• Implementation plans
• Progress updates
• Roadmap status

Best for: Understanding project status, contributing

5. Session Summaries (sessions/)

Development sessions:

• What was built
• Decisions made
• Problems solved
• Next steps

Best for: Understanding context, reviewing history

---

Documentation Standards

File Naming

• Use kebab-case: my-document.md
• Be descriptive: BUILD-QUICK-REF.md not BUILD.md
• Add prefixes for categories: PHASE-2.4-COMPLETE.md

Headings

• Start with H1 (#) for title
• Use H2 (##) for major sections
• Use H3 (###) for subsections
• Include table of contents for long documents

Links

• Use relative paths: ../README.md
• Link to specific sections: #installation
• Keep links up to date when reorganizing

Examples

• Include practical examples
• Show both good and bad patterns
• Provide context and explanation
• Keep examples focused and concise

---

Maintenance

Adding New Documentation

1. Choose appropriate directory
2. Follow naming conventions
3. Update INDEX.md
4. Update this file if adding new category
5. Cross-link from related documents

Updating Documentation

1. Update modification date
2. Maintain backward compatibility of links
3. Update cross-references
4. Run link checker (if available)

Reorganizing

1. Update all internal links
2. Update INDEX.md
3. Update this file
4. Create redirects if needed (GitHub Pages)
5. Announce in changelog

---

Search and Discovery

Documentation Index

The Documentation Index is the master catalog:

• Organized by topic
• Links to all documents
• Quick reference tables
• Statistics and metrics

Full-Text Search

Use GitHub's search:

1. Navigate to repository
2. Press / to open search
3. Search within: path:docs/
4. Example: path:docs/ quickstart

Directory Listing

Each category has its own folder:

• ls docs/guides/ - List all guides
• ls docs/api/ - List all API docs
• ls docs/phases/ - List phase documents

---

Related Resources

External Documentation

• SPEC/: Language specification (formal grammar, type system)
• GOVERNANCE/: Governance and compliance docs
• .roadmap/: Project roadmap and planning
• examples/: Code examples
• test/: Test documentation

Repository Links

• Issues: https://github.com/personalayer/pcl/issues
• Discussions: https://github.com/personalayer/pcl/discussions
• Pull Requests: https://github.com/personalayer/pcl/pulls

---

Quick Links

Documentation	Location
Main Index	docs/INDEX.md
Quickstart	docs/quickref/QUICKSTART.md
Getting Started	docs/guides/GETTING-STARTED-CURRENT.md
Build System	docs/BUILD-SYSTEM.md
Skills CLI	docs/skills/CLI-USAGE.md
API Reference	docs/api/
Contributing	CONTRIBUTING.md

---

Maintained by: PCL Team Questions: GitHub Discussions Issues: GitHub Issues