Contributing

Contributing

The plugin is small, focused, and conservative. Contributions are welcome but please align with the design principles before opening a PR.

Design principles (read before contributing)

1. No chunking, no embeddings. Binaries get paired companion .md files. Box AI Extract handles OCR when available; we don't ship our own.
2. Append-only memories. Don't overwrite. Mark old memories superseded and write new.
3. Box file IDs are the only reliable identifier. Filenames change; wikilinks rot. File IDs are forever.
4. Tier-aware, never tier-gated. Every feature has a working path on every Box tier — Business+ just gets faster paths.
5. Folder ACLs are the multi-team boundary. Frontmatter team: is a hint; folder permissions are enforcement.
6. Box MCP is the auth boundary. Plugin doesn't manage Box auth — uses whatever Box MCP your agent has.

See Architecture for the full rationale.

What we accept

• New operational quirks for operational-notes.md
• Bug fixes in existing skills
• Improvements to deep-reference docs in references/skills/<name>-detail.md
• New skills that genuinely extend the model (not duplicates of existing)
• Tier-detection refinements as Box's plan structure evolves

What we decline

• Skills that wrap deprecated Box features (Box Skills framework, self-hosted Box MCP)
• Embeddings / vector store integrations — Box AI Hubs Q&A does this; we don't reimplement
• Chunking / RAG patterns — see Architecture for why
• Skills that work around the Cowork plugin format instead of fitting within it
• Box auth handling — leave that to the Box MCP

PR checklist

• claude plugin validate . passes
• scripts/build.sh produces clean zip artifacts (drift check + airgap scan pass)
• If schema changes: PR here first, then bump pin in BOX-Onprem
• SKILL.md frontmatter is ASCII only (no em-dashes, no smart quotes)
• Body H1 uses slash form (# /skill-name)
• If touching references/, sync per-skill copies in skills/<name>/references/
• CHANGELOG entry added for user-facing changes
• If new SKILL.md is added: update README skill table + Wiki Skills Reference

How the on-prem repo stays in sync

The schema, tier matrix, architecture, and operational notes live here as the source of truth. mrdulasolutions/BOX-Onprem pins to a specific commit of this repo via its .schema-pin file. When schemas change here, the on-prem repo bumps the pin in a separate PR.

This means: schema changes need to land here first.

Reporting bugs

• Standard bugs: https://github.com/mrdulasolutions/BOX/issues
• Security issues: see SECURITY.md in either repo

See also

• Architecture — design rationale
• Schema — schema-evolution discipline
• Cloud repo: https://github.com/mrdulasolutions/BOX
• On-prem repo: https://github.com/mrdulasolutions/BOX-Onprem