Getting Started with Your Comms Hub

Welcome aboard. This guide walks you from a fresh sign-in to a published, syndicated piece of content. It is meant to be read once, top to bottom, in about ten minutes, and then kept open in a tab while you set things up.

If you only have two minutes: jump to §3 The Daily Loop.

1. What the Comms Hub Is

The Comms Hub is the planning room for everything your team publishes. It pulls signal from the repositories you care about, turns that signal into draft content with the help of AI, lets you edit and approve, and then syndicates the finished piece to your newsletter list, your blog, and your social channels, from one place.

It follows the POSSE principle: Publish on your Own Servers, Syndicate Everywhere. Your content lives in your repos and your CMS first; the Hub does the legwork of fanning it out.

The Hub is built on Hugo for the static shell, Cloudflare Pages for hosting, Clerk for authentication, Cloudflare Workers for the API, and Brevo, Buffer, and GitHub for syndication. You will not need to know any of that to use it, but it is the substrate beneath every button.

2. The Eight Surfaces

When you sign in, seven destinations live in the left sidebar (plus the AI Assistant that hovers on the right). Here is what each one is for.

2.1 Dashboard

Your home base. Cards on this page show the latest activity across every repo you have connected: open content issues, in-flight drafts, freshly generated ideas, and recent publishes. It is the page you check first thing in the morning and last thing before you close the laptop.

If a card surfaces a piece of content that is ready for your attention, the card title links straight into the relevant tool, Writer, Schedule, or Ideas.

Your articles is the panel just below the header. Every piece you have generated, drafted, or published lives here, drafts and published pieces side by side, each tagged with a status pill so you can tell them apart at a glance. Click Edit in Writer on any row to jump straight into editing; the Writer opens with the body, frontmatter, and publish state already loaded.

2.2 Schedule

A calendar view of every scheduled and published piece. Filter by project, by type (newsletter, blog, social, announcement), or by status (draft, review, approved, scheduled, sent, published).

Three things to know:

• Newsletters dispatch at 08:00 UTC via GitHub Actions and Brevo.
• Blog cross-posts publish at 09:00 UTC to whichever repo the frontmatter names as target_repo.
• Social posts route through Buffer to whichever channels the frontmatter names in buffer_channels.

The Schedule view is also where you drag posts between days to rearrange the calendar.

2.3 Ideas

The Ideas page is your brainstorm surface. It groups raw signal from your repos (GitHub issues, recent commits, releases) into draft content ideas you can promote into the Writer.

Click an idea to expand it. Use Send to Writer to turn an idea into a draft, or Send to Schedule to slot it into the calendar without writing yet.

Ideas can also be hand-typed; you do not have to wait for AI to surface something.

2.4 Writer

The Writer is where AI-assisted drafting happens. Open a draft (or start a new one) and the right side becomes a rich editor. The left side has tools:

• Industry Watch, a Gemini-backed radar that scans recent news in your industry and proposes article angles, complete with citations and Creative-Commons image suggestions from Openverse.
• Auto-research, kick off a multi-source dig on a topic; the result is a structured dossier with sources, quotes, and suggested headlines.
• Image library, every Creative-Commons image you have saved per piece, plus the gallery of AI-generated banners.
• Fact-checker agent, runs claims in the draft through a verification pass with cited sources.

The editor toolbar above the textarea has all the rich-content controls:

• Bold / Italic / Heading / Link / List, standard markdown formatting.
• Image, opens a picker with Openverse search (Creative-Commons only) and local-file upload. Drag-and-drop or paste also works straight into the textarea.
• Diagram Studio, the diamond/box icon. Opens an AI-powered modal that reads your article and proposes Mermaid diagrams that fit it. See section 2.4.1 below.
• Preview, toggles a live preview pane that renders Mermaid diagrams and images alongside your prose.

Above the toolbar you will see the publish-state controls (only visible when an article is loaded from “Your articles”):

• Status pill, Draft or Published, driven by the article’s frontmatter.
• Save, persists your edits to the backing row immediately, without publishing.
• Publish / Re-publish, pushes the current body to the configured target_repo / target_path via the GitHub Contents API. Idempotent: HEADs first for the existing file SHA, PUTs with it, records the resulting commit back into frontmatter. Works for first publishes AND for editing-after-publishing.

Drafts are autosaved as you generate. You can Send to Schedule to slot a finished piece into the calendar, or Discard draft to bin it.

2.4.1 Diagram Studio (AI Mermaid diagrams)

Click the diagram icon on the editor toolbar to open the studio. It auto-analyses your article body, your image alt text, and any existing Mermaid blocks, then proposes up to three Mermaid candidates with:

• A location hint (which heading or paragraph the diagram should sit near)
• A diagram type (flowchart, sequence, class, state, ER, journey, gantt, mindmap, timeline, quadrant)
• A live rendered preview so you see the diagram before accepting
• A one-line rationale for why the AI picked that type for that location

Click Use this diagram to insert the Mermaid block at your cursor. Or type natural-language feedback under any candidate (“use horizontal layout”, “add a decision node for X”, “convert to a sequence diagram”) and click Refine with feedback, the preview updates in place. The studio honestly returns zero suggestions if your article does not benefit from a diagram, rather than forcing one. Insert blank template is always available as a fallback. Click Help in the modal header for the full reference.

2.4.2 Auto-generated SEO

When you open a published article in the Writer the Plan phase populates target keywords and a meta description automatically. The analysis runs against your full body, every image alt text, and every Mermaid diagram source, so visually-emphasised concepts that recur in alt text get keyword weight. The 0/160 character counter on the meta-description block goes amber if you slip outside the 120-160 sweet spot. Click Auto-generate SEO from content at any time to re-run after edits.

2.5 Research

Research is the deeper, slower cousin of the Writer’s auto-research. It produces saved dossiers (multi-page briefings on a topic, with persisted sources) that you can reference from any number of future drafts. Think of it as your reusable knowledge base.

A typical use: before launching a product, run a Research pass on the competitive landscape; that dossier then feeds the next eight pieces of content.

2.6 Social

The Social page is the multi-channel syndication console. Select a published piece and the Social page generates platform-appropriate posts for each channel you have configured (LinkedIn long-form, X threads, Bluesky single posts, Mastodon, and so on), each in the right voice and the right length for the platform.

Approve, edit, or regenerate per-channel. Approved posts are pushed to Buffer for scheduling.

2.7 Settings

Three sub-areas:

• Repositories, which repos the Hub watches. Toggle them on or off. Connect new ones.
• Brand, your logo, colours, voice samples, brand-voice rules. The Hub reads this every time it generates copy so the AI sounds like you.
• Integrations, your Brevo list IDs, your Buffer channels, your Clerk team members.

If something feels off-brand, this is the first place to look.

2.8 The AI Assistant

The chat panel that slides out from the right. Ask it to find trends, brainstorm ideas, write a paragraph, suggest a headline, summarise a long thread, or pull together a quick research dig. It has tools (it can actually open Industry Watch for you, save an image, draft a post, and so on), not just chat about doing those things.

If you forget where a feature lives, ask the Assistant. It will route you.

3. The Daily Loop

A recommended daily cadence, once you are set up:

1. Morning (5 min), open the Dashboard. Triage anything in the In Review column. Drag two items into Approved if they are ready.
2. Mid-morning (15 min), open Ideas. Promote one idea into the Writer, run auto-research, and produce a first draft. Save and move on.
3. Afternoon (10 min), open Writer, finish the morning’s draft. Fact-check. Send to Schedule for tomorrow 09:00 UTC.
4. End of day (5 min), open Social. Look at the posts queued for yesterday’s publish; approve or tweak.

Total: about thirty-five minutes a day, and you ship a piece of content every weekday.

4. Status Flow

Every piece of content moves through this status flow, regardless of type:

draft  →  review  →  approved  →  scheduled  →  sent / published

• draft, in progress, not ready to be seen by anyone outside the editor’s chair.
• review, ready for a teammate to read.
• approved, sign-off has happened; the piece is ready to schedule.
• scheduled, placed on the calendar with a publish date.
• sent (newsletters) / published (blog, social), out the door.

You can drag pieces between statuses on the Schedule view, or change the status from inside the Writer.

Published is not the end. Open any published piece via “Your articles” → Edit in Writer, make changes, and click Re-publish. The Writer reuses the original target_repo / target_path and produces an idempotent update commit on the destination, no duplicates, no orphan files, full audit trail.

5. Frontmatter, The Source of Truth

Every piece of content is a Markdown file with frontmatter at the top. The Hub generates this for you, but it is worth knowing what the key fields do, especially when you want to override the AI:

If a piece is not behaving as expected (going to the wrong audience, missing a channel) the answer is almost always in the frontmatter.

6. Your Brand Voice

The AI in the Writer, the Industry Watch radar, the Social generator, they all read your brand voice file before producing anything. The file lives in Settings → Brand → Voice and accepts:

• Tone descriptors (“dry, technical, mildly ironic, never breathless”)
• Banned phrases (“we are excited”, “in today’s fast-paced world”)
• Sample paragraphs (paste two or three pieces you are proud of)
• Audience persona (who you are writing to)
• Reading-level target (e.g. “Grade 9–11; concrete over abstract”)

The more you put here, the less editing you will do later. Two paragraphs of strong samples beats a hundred adjectives.

7. Industry Watch, A Worked Example

To make the Writer concrete, here is the canonical first-day workflow:

1. Open Writer → New Draft.
2. Click Industry Watch in the left tool rail.
3. Pick the project this article is for (the Hub knows your projects from projects.yaml).
4. The radar fetches recent news, ranks each item by relevance to your customer (not to the project, that is the v1.0.2 fix), and shows a card list.
5. Pick an item. The Hub fetches the full article, extracts quotes, finds Creative-Commons banner images on Openverse, and proposes Mermaid diagrams if the topic is technical.
6. Click Draft Article. The Hub produces a 600–900 word piece with inline links to its sources, an og:image banner, and a suggested social blurb.
7. Edit the draft. Save. Send to Schedule for tomorrow.

The whole loop takes about twelve minutes from sign-in to scheduled.

8. Cross-Project Publishing

If your team manages content for several projects (yours and your clients’), each piece carries a project: field in its frontmatter. The Hub uses that to:

• Pick the right Brevo sender email and audience
• Theme the preview with the project’s brand colour
• Cross-publish the blog post to the project’s own repo (via target_repo)
• Tag the social syndications with the project’s handles

You can filter every view (Dashboard, Schedule, Ideas, Writer) by project from the project switcher at the top of the page.

9. Approvals and Roles

Clerk handles team membership. Roles available:

• Owner, full control, can change billing and roles.
• Editor, can publish anything in any project.
• Drafter, can produce drafts and request review, but cannot publish.
• Viewer, read-only.

Invite teammates from Settings → Team.

10. Tips & Gotchas

A short list of things that surprise new users:

• All timestamps are UTC. Newsletters dispatch at 08:00 UTC and blogs at 09:00 UTC. Set your timezone offset in your head once and you are fine.
• Drafts autosave every 15 seconds. You will not lose work to a tab crash, but be careful with destructive edits, undo only goes back about 50 steps.
• Industry Watch will not invent quotes. If a source does not have a quotable line, Industry Watch will say “no quotable line found” rather than fabricate one. This is intentional.
• Generated images are Creative-Commons sourced from Openverse, attributed automatically. You do not need to add attribution yourself; the Writer embeds it in the og:image and the footer.
• The AI Assistant has memory inside a single session, not across. Closing the tab clears its context.
• You can edit any field from the Writer, including the URL slug, useful when the AI picks an unwieldy one.
• Frontmatter status: scheduled does not publish anything. Only scheduled_at in the future plus the daily dispatch workflows do. If status is scheduled and scheduled_at is in the past, nothing happens, the workflow logs a warning.

11. Getting Help

Three paths, in increasing order of urgency:

1. The AI Assistant, for “how do I…” questions. It knows the Hub.
2. office@sanmarcsoft.com, for “something is broken” or “I want to change my billing”.
3. The status page (status.sanmarcsoft.com) for “is it just me?”. If a syndication channel is down, you will see it here before you see it anywhere else.

12. What’s New in This Release

The 2026-05-13 release adds the full edit-and-republish loop plus AI-assisted rich content. Highlights:

• Edit published articles in the Writer. “Your articles” on the Dashboard now shows drafts AND published pieces side by side, each with a Draft / Published status pill. Click Edit in Writer on any row to open the full Writer with body, frontmatter, and publish state pre-loaded.
• Save and Re-publish toolbar. The Writer now has dedicated Save and Re-publish buttons next to Generate. Save persists edits to the backing row immediately. Re-publish pushes to the configured target_repo / target_path via the GitHub Contents API. Idempotent: it HEADs for the existing SHA, PUTs with it, and writes the commit info back into frontmatter, works for first publishes AND for editing-after-publishing.
• AI Diagram Studio. The Mermaid toolbar button now opens a studio that reads your article and proposes up to three Mermaid candidates (with location hints, type tags, live rendered previews, and one-line rationales). Pick one to insert, or type natural-language feedback to refine any candidate in place. The studio honestly returns zero suggestions if your article does not benefit from one. An integrated Help panel covers everything, including supported diagram types and a privacy note.
• Auto-generated SEO + meta description. When you open a published article the Plan phase populates target keywords and a 140-160-character meta description automatically, derived from body content, image alt text, AND Mermaid diagram source. A 0/160 counter goes amber outside the sweet spot. Re-run any time via “Auto-generate SEO from content”.
• Image uploads. The image-picker now supports local-file upload (PNG / JPG / WebP / GIF / SVG up to 10 MB) alongside Openverse search. Drag-and-drop or paste an image into the textarea to upload directly.
• Live preview pane. Toggle the eye icon on the toolbar to see the article rendered with Mermaid diagrams and images, side-by-side with the markdown source.

Earlier this season (the v1.0.2 baseline):

• Industry Watch radar, comms-manager perspective via Gemini + Google Search, with relevance scored against your customer, not your project.
• Creative-Commons image picker, Openverse-backed, with smart keyword suggestion from the article body.
• Mermaid diagrams, inline in technical pieces, rendered automatically (the legacy blank-template insert, now superseded by Diagram Studio).
• Saved drafts on the Dashboard, your in-flight pieces visible from the home page (since renamed to “Your articles” and extended to include published pieces).
• Send to Writer / Send to Schedule, promote a draft from the Dashboard or Ideas without a context switch.
• Per-piece image gallery, each piece keeps its own Creative-Commons image library.
• Style banner + Discard draft, visual confirmation of which brand voice is loaded, plus a one-click bin for false starts.
• Three-stage customer profile pipeline, better relevance, fewer off-brand recommendations.
• Vertex source URLs in human-readable form, when the AI cites a source, you can read it.

You Are Ready

That is the tour. Open the Dashboard when you finish reading, and the Hub will walk you through finishing the repo connection in onboarding. Anything that confuses you, ask the AI Assistant, it will route you.

Welcome to the Comms Hub.