This page describes every top-level workspace and its purpose.

perchance-bot-workshop/
├── .github/              # GitHub config, PR templates, CI workflows, Copilot instructions
├── agents/               # Agent workspace guidance
├── archive/              # Retired historical assets
├── bots/                 # Bot lifecycle workspaces
│   ├── templates/        #   Starter export templates
│   ├── in-progress/      #   Active bot development
│   └── completed/        #   Release-ready validated bots
├── docs/                 # Standards and verification docs
│   └── Code_Documentation/  # Perchance platform reference docs (legacy name)
├── scripts/              # Automation scripts (validation, transforms)
├── shared/               # Shared prompts, utilities, schemas
├── snippets/             # Small reusable fragments and examples
├── tests/                # Validator tests and fixtures
│   └── fixtures/         #   Valid and invalid test cases
├── tools/                # Tooling notes and support resources
└── wiki/                 # This wiki

The core workspace organized by lifecycle stage:

• templates/ — Canonical starter assets. Contains import-safe export envelopes. Use perchance-empty-minimal.json by default for new builds.
• in-progress/ — Active development. One folder per bot in kebab-case. Must not be treated as released.
• completed/ — Release-ready bots only. Promotion requires documented verification. Each bot folder should contain a versioned export JSON and a RELEASE.md.

Standards and process documentation:

• PERCHANCE_IMPORT_VERIFICATION.md — Mandatory release gate for any export JSON work. Defines the export envelope contract, canonical tables, and verification checklist.
• Code_Documentation/ — Reference documentation for Perchance platform features (custom code, messages, styling, plugins, etc.).

Repeatable automation:

• validate-perchance-export.js — Validates a Perchance export JSON against import-safety requirements. Fails with actionable errors and non-zero exit code.

Cross-bot reusable assets organized into:

• prompts/ — shared prompt assets
• utilities/ — reusable helper modules
• schemas/ — shared data contracts and formats

Small reusable fragments for fast composition. Indexed in SNIPPETS_INDEX.md. Categories include: export-envelope, custom-code-ui, validation, json-serialization, message-objects, shortcut-buttons, workflow-docs.

Verification assets:

• test-validate-perchance-export.py — Python unittest suite for the export validator
• fixtures/valid/ — Known-good test exports
• fixtures/invalid/ — Intentionally broken exports for failure testing

Helper utilities and tooling resources broader than one-off scripts.

Historical storage for inactive, deprecated, or superseded assets. Not a source for new work.

• Folders and files: kebab-case (e.g., my-bot-name, validate-perchance-export.js)
• Bot exports: <bot-name>-vMAJOR.MINOR.PATCH.json
• Governance files: UPPER_CASE with underscores (e.g., PROJECT_RULES.md)

When making structural changes, update these files in the same PR: