0.4.x-ImportExportCollaboration.md

Import, export, and collaboration (Feature Draft)

Status: Draft
Updated: 2026-05-20
Owner: Core
Purpose: Draft for content import/export, LLM collaboration formats, scoped exports, operation-based changes, and diff review.

Overview

• Defines how content can be exported with configurable scope and formatting.
• Covers operation-based imports for adding, removing, or modifying content with review before processing.
• Supports human review, LLM collaboration, backup workflows, and future API integrations.
• Keeps machine-assisted changes inspectable before they modify project data.

Outline

Import/export should support collaboration between humans, automation, and LLMs without making blind changes. Exports should be scoped, deterministic, and readable. Imports should be operation-based: add, update, remove, move, publish, archive, relate, add language variant, update language variant, add generic variant, or update generic variant through explicit operations that can be validated and reviewed before application.

The canonical collaboration format should be JSON operations that may contain Markdown field content. These operations can be submitted through the API or pasted into a web interface. Export files are not expected to be directly re-importable backups.

For LLM collaboration, exports should optionally include a resolved context bundle. A scoped export may start from one content item, follow direct reference fields, inverse references, controlled query fields, and approved resolver suggestions, then include the selected related entities with stable identifiers and enough relationship metadata for the assistant to navigate the project graph.

Context bundles should use the resolver graph rather than ad-hoc content traversal. Export formatters can start from an entity, walk outgoing references, incoming references, controlled query results, and approved resolver suggestions, then include a bounded set of related entities. The resulting bundle should include relationship metadata and resolver diagnostics so the user can understand why a piece of context was included.

Inline resolver tokens should be exportable in an LLM-readable form. Instead of requiring an assistant to understand and resolve internal shortcodes, exports may render them as explicit tagged spans such as [ref:character/bernd]Bernd[/ref] or [query:scene-context?limit=5]...[/query]. The visible text remains readable, while the tag tells the assistant where related context can be requested or inspected. Imports may convert supported tagged spans back into the internal dynamic token format after validation, keeping stored content non-destructive and re-resolvable.

The web collaboration workflow should favor diff review. A proposed import may be valid, but it should still show what will change and require confirmation when it affects stored content, URLs, publication state, schema definitions, module configuration, or theme files. API imports cannot rely on interactive confirmation, so they must depend on scoped tokens, validation, versioning, operation logs, and clear failure reporting.

This feature should not replace backup/restore. Import/export is for structured collaboration and selective movement of content or configuration; backup/restore is for operational recovery.

Technical Specifications

• Define export scopes such as content item, content tree, content type/schema, media references, theme metadata, or module configuration where applicable.
• Define context export scopes that can start from one content item and include directly referenced entities, inverse references, controlled query results, and optionally approved resolver suggestions.
• Build LLM context bundles from the resolver graph and its visited-reference/context-gathering services where available.
• Include relationship metadata such as source field, reference type, direction, language, variant, and resolver status in context exports where useful.
• Define a canonical operation model before supporting several file formats.
• Use JSON operations as the canonical exchange format.
• Allow Markdown content inside operation payloads where fields use Markdown.
• Support API import of JSON operations and web-interface copy/paste import of JSON operations.
• Do not treat exported files as backup artifacts or guarantee direct re-import of export files.
• Suggested operation types:
  • create
  • update
  • delete
  • move
  • publish
  • archive
  • relate
• Validate operations before producing a diff.
• Show diffs before applying operations.
• Require web-interface imports to run dry-run validation and show a diff before explicit user confirmation.
• Allow API imports to apply without interactive diff confirmation, relying on validation, scoped token permissions, content versioning, and operation logs.
• Preserve stable identifiers where possible.
• Preserve durable content UIDs, versions, languages, generic variants, and field identifiers where possible.
• Include audit, publication, visibility, and ACL metadata only when the export scope and actor permissions explicitly allow it.
• Include flexible metadata payloads such as SEO hints or OpenGraph data when the export scope includes content metadata.
• Include reserved base field values such as title and subtitle through schema-backed field export, not through metadata export.
• Export and import database-backed schema Twig as schema metadata, with validation before apply.
• Export and import controlled content-query/list field definitions as structured field content, not executable template logic.
• Resolve references explicitly and report missing or ambiguous targets.
• Include resolver diagnostics in dry-run/export reports when context gathering finds missing, ambiguous, cyclic, or ACL-restricted references.
• Preserve relationship intent for reference fields, query fields, and inline resolver tokens where possible.
• Expand internal resolver tokens to LLM-readable tagged spans in export formats that target assistant collaboration.
• Parse and validate supported tagged spans in import payloads, then normalize them back to internal dynamic resolver tokens where configured.
• Treat tagged-span normalization as a reviewable import transformation and include it in dry-run diffs.
• Keep tagged-span normalization non-destructive: validated spans should become dynamic internal resolver tokens, not hard-coded resolved content.
• Preserve enough operation metadata to show when JSON operations modify reference fields, query fields, or resolver tokens.
• Keep context bundles bounded by explicit depth, item limits, ACL checks, and export scope so they do not accidentally expose an entire project.
• Use Symfony Serializer for normalized export structures where practical.
• Use Validator constraints for operation validation.
• Use result objects for invalid, requires_review, applied, and failed states.
• Use Messenger for large import processing after review.
• Log applied import batches with actor, source, scope, and operation summary.
• Make export formatters additive through tagged services.
• Make import parsers additive through tagged services.

Testing & Validation

• Test export determinism for stable fixtures.
• Test import validation rejects missing identifiers, invalid references, and unsupported operations.
• Test diff generation before apply.
• Test web copy/paste imports require dry-run diff confirmation before apply.
• Test API imports apply through scoped-token permissions without interactive confirmation.
• Test apply behavior for each operation type.
• Test partial failure handling and rollback expectations.
• Test permissions for export, preview, and apply.
• Test ACL-restricted metadata is exported only with explicit permission and scope.
• Test flexible metadata round trips without being confused with schema field values.
• Test reserved base field values such as title and subtitle round trip as schema field values.
• Test round trips for at least one content scope.
• Test language and generic variant round trips.
• Test schema Twig import validation before apply.
• Test field identifiers survive export/import round trips.
• Test context exports include only allowed referenced entities and respect depth, limit, ACL, language, and variant settings.
• Test context exports use resolver graph data and include expected relationship metadata.
• Test resolver diagnostics appear in dry-run/export reports.
• Test resolver-token export expansion and tagged-span import normalization.
• Test tagged-span import normalization remains non-destructive.

Implementation Notes

• Decision recorded: Model imports as validated operations with mandatory diff review before apply.
• Decision recorded: Import/export must preserve content UID, version, language, generic variant, and field identifier information where relevant.
• Decision recorded: Audit, publication, visibility, and ACL metadata require explicit export scope and permissions.
• Decision recorded: Flexible metadata payloads may be imported/exported as content metadata and must remain distinct from schema field values.
• Decision recorded: Keep import/export separate from backup/restore.
• Decision recorded: Make parsers and formatters additive extension points.
• Decision recorded: Canonical collaboration format is JSON operations, optionally containing Markdown field content.
• Decision recorded: Imports can be submitted through the API or through a web-interface copy/paste workflow.
• Decision recorded: Export files are not designed as backup artifacts and are not guaranteed to be directly re-importable.
• Decision recorded: Web-interface imports require dry-run validation, diff review, and explicit confirmation before apply.
• Decision recorded: API imports cannot rely on interactive confirmation and instead use scoped tokens, validation, versioning, operation logs, and failure reports.
• Decision recorded: Multi-operation imports should rely on versioning plus operation logs, with transactional execution where practical and clear partial failure reporting where full transactionality is not possible.
• Decision recorded: Unpublished content is exported only with explicit permission and scope.
• Decision recorded: LLM collaboration exports may include bounded context bundles that follow direct references, inverse references, controlled query results, and approved resolver suggestions from a starting entity.
• Decision recorded: Context bundles should use the resolver graph/visited-reference services instead of ad-hoc traversal when available.
• Decision recorded: Assistant-facing exports may render internal resolver tokens as explicit tagged spans, and imports may normalize supported [ref:...]...[/ref] or [query:...]...[/query] spans back to internal dynamic tokens after validation.
• Decision recorded: Tagged-span normalization is non-destructive and should preserve dynamic resolver intent rather than storing resolved content as fixed text.