Skip to content

Article Publish and Sync Procedure

Purpose

This procedure defines how article-domain cleanup work is turned into persisted CMS state through the BFF.

It is the operational companion to CMS Persistence Workflow.

Scope

This procedure applies to:

  • article objects
  • article collections
  • collection membership updates

Preconditions

Before publish or sync:

  1. the local article or collection artifact has been cleaned and reviewed
  2. slugs and keys are stable enough for persistence
  3. referenced media URLs are valid
  4. collection membership targets exist or are being created in the same publish cycle

Publish Decision

For each changed article-domain artifact, decide:

  • create if there is no corresponding BFF object yet
  • update if the BFF object already exists
  • membership-sync if the collection exists but members changed

The assistant should first query BFF for current state.

Article Object Procedure

  1. Read the local source from docs/articles/<slug>.md.
  2. Extract identity, content, media, taxonomy, and author fields.
  3. Query BFF using getArticle(slug) or getArticleById(articleKey).
  4. Validate before write:
  5. slug uniqueness
  6. required fields present
  7. hero image fields present
  8. category and tag shape valid
  9. Persist:
  10. createArticle(input) if missing
  11. updateArticle(articleKey, input) if present
  12. Re-read from BFF and verify key, slug, title, and updated fields.

Article Collection Procedure

  1. Read the local source from docs/articles/collections/<collection>.yaml.
  2. Extract collection identity, description, media, and member slugs.
  3. Resolve member articles to actual BFF article identities.
  4. Query BFF using getArticleCollection(collectionKey) or listing.
  5. Persist collection object:
  6. createArticleCollection(input) if missing
  7. updateArticleCollection(collectionKey, input) if present
  8. Sync membership:
  9. addArticlesToCollection
  10. removeArticlesFromCollection
  11. replaceArticlesInCollection
  12. Re-read the collection and verify metadata and member set.

Safe Publish Rule

Do not persist on ambiguous identity.

Examples:

  • two plausible target articles with conflicting keys
  • uncertain whether a collection key is new or renamed
  • local artifact references articles not yet present in BFF

Resolve the ambiguity before write.

Transition Rule

Current scaffolding may still read local article artifacts directly.

That does not remove the publish obligation.

During transition, local files are:

  • staging input for scaffold compatibility
  • staging input for BFF/CMS persistence

not the terminal state of cleanup work.