Decap CMS intake path for briefs, guides, and tips

This document outlines how to add a browser-based authoring path using Decap CMS (formerly Netlify CMS) while keeping the JSON-driven static build authoritative. It retains the existing per-type directories (zephtech-site/content/feed/, zephtech-site/content/guides/, zephtech-site/content/tips/) and enforces the same validation requirements used in the GitHub issue-to-PR workflow.

Why Decap CMS fits this stack

Git-native writes: Decap CMS commits directly to the Git repository through Git Gateway or the GitHub backend, preserving version history and auditability.
No placeholder content: The CMS can require all schema fields before committing so only fully sourced, production-ready briefs land in the repo.
Minimal front-end surface area: Hosting the admin UI under /admin/ keeps it isolated from the public site while leveraging Netlify Identity (or your SSO) for authenticated authors.

Implementation blueprint

Add the admin shell in zephtech-site/public/admin/index.html that loads Decap CMS from the official CDN (https://unpkg.com/decap-cms@^3/dist/decap-cms.js). Keep this page behind Netlify Identity by enabling NETLIFY_IDENTITY=enabled in the site settings and restricting registration to approved users.
Create zephtech-site/public/admin/config.yml pointing to the GitHub repository that hosts this site. Set the branch to the default branch (confirm with git symbolic-ref --short HEAD in production) and use the media_folder under zephtech-site/public/uploads so assets remain versioned.
Define three collections that mirror the existing content layout: - briefs targeting content/feed/ with fields for title, slug, published, pillar, topics (list), summary, body_html (markdown widget with HTML output), reading_time_minutes, sources (list of objects with category, title, url, summary, source, published), and the existing analytics fields. Mark every field required so authors cannot submit partial entries. - guides mapped to content/guides/ with the same metadata and body_html structure; ensure slug plus published date align with the site’s routing rules documented in reports/brief-intake-via-github.md. - tips mapped to content/tips/ with required metadata, short-form body_html, and the same sourcing rules (no unsourced claims).
Enforce validations using Decap widgets: - Use pattern constraints for slug (lowercase letters, numbers, and hyphens), published (ISO 8601 YYYY-MM-DD), and url fields (HTTPS only). - Require at least two sources entries for briefs and at least one for guides/tips to keep the “real data only” rule intact.
Gate merges via PRs: Configure publish_mode: editorial_workflow so Decap opens pull requests instead of committing directly to the default branch. This keeps the existing QA and build checks in place before content goes live.
Keep the build authoritative: Add a Netlify build hook (or GitHub Action) that runs python scripts/build.py after Decap commits land, ensuring the static pages and feeds are regenerated from the committed JSON files before deployment.

Operational safeguards

Identity and roles: Restrict Decap CMS access to verified staff accounts. Disable public signups and require MFA where available.
Schema drift prevention: Mirror any future schema changes first in the JSON validators and then in config.yml so the CMS cannot emit malformed records.
Source integrity: Reject submissions with unreachable URLs or missing summary fields in sources. Periodically lint the repository with a CI job that checks link reachability and schema conformance.

Rollout checklist

[ ] Add public/admin/index.html and public/admin/config.yml with the collections above.
[ ] Enable Netlify Identity with role-based access and connect Git Gateway to the GitHub repo.
[ ] Turn on editorial workflow so every Decap submission opens a PR for review.
[ ] Wire the deployment pipeline to rebuild from JSON after merges (no runtime edits).
[ ] Document the author instructions in the contributor guide so writers know the sourcing and validation rules.