qalma: Instructions file for Codex

Qalma Repository Guidance

Mission

Build an Angular-first, headless, plugin-based rich text editor on ProseMirror. The product should offer the composability expected from modern editors such as Plate or Tiptap while feeling native to Angular.

The public developer experience is the product. Prefer typed Angular-facing contracts, signal-based state, consumer-owned UI, accessibility, and deliberate extension points over exposing raw ProseMirror details.

Repository Skills

• Use qalma-architecture for product vision, repository structure, public API design, new library boundaries, and architectural refactors.
• Use qalma-plugin-development whenever adding, changing, reviewing, or removing an editor plugin, command, mark, node, shortcut, or ProseMirror behavior.
• Use qalma-docs-sync after adding, changing, reviewing, or removing a public plugin capability that affects apps/docs, docs navigation, playground behavior, libs/editor/README.md, or durable workflow guidance.
• Use git-commit when the user invokes /commit or asks to generate and create a conventional commit from staged changes.
• Use qalma-release when discussing or changing versioning, the release scripts, the GitHub Actions release workflow, Nx release configuration, or npm publishing for @qalma/editor.

Architectural Invariants

• Keep libs/editor headless. Do not bake toolbar buttons, product styling, or a fixed feature set into editor primitives.
• Let consumers select plugins in TypeScript and compose their UI explicitly through Angular templates and content projection.
• Treat apps/sandbox as a real consumer and executable documentation. It must use only the intentional public API from @qalma/editor.
• Keep ProseMirror as the internal engine. Expose it publicly only after an explicit API design decision.
• Let a QalmaPlugin contribute schema nodes or marks, commands, command states, shortcuts, and ProseMirror plugins.
• Expose configurable features through Qalma-owned option interfaces, immutable defaults, and validation. Do not leak a third-party options object as the public contract by default.
• Keep first-party plugins in libs/editor/src/lib/plugins until a real dependency, release, ownership, or bundle boundary justifies a dedicated lib.
• Preserve unique plugin keys, schema names, command names, and shortcuts.
• Validate every persisted first-party node/mark attribute at the ProseMirror schema boundary. Treat HTML, JSON, Markdown, paste/drop, migrations, upload metadata, AI output, and collaboration metadata as untrusted; build fresh allowlisted DOM attributes instead of merging untrusted attribute bags.
• Keep the public barrel intentional and small. Do not export internal ProseMirror helpers or compatibility aliases without a concrete need.
• Keep plugins/qalma as the public agent skill pack for Codex, Claude-compatible skill loaders, and other agents that consume SKILL.md folders.