Skip to content

0010 — Document library moves into the portal, gated by Form O

  • Status: Accepted
  • Date: 2026-05-09
  • Decision owners: Gina Lyn Cox · Operations Lead
  • Related: ADR-0004 (Forms Permissions Architecture) · ADR-0005 (Community Platform — BuddyBoss) · ADR-0007 (Library Architecture & Three-Tier Video Hosting) · Form O (Ecosystem Role & Permissions Matrix) · guildcommerce-core-plugin / library

Context

The blueprint repo currently publishes a public MkDocs Material site at ginalyncox.github.io/ganjier-guild-launch-blueprint/. That site is what the rest of this repo refers to as "the document library."

Three things have changed since that site went up:

  1. The new guildcommerce-theme is staging on the Cloudways sandbox as the replacement for the YOOtheme production site on ganjierguild.com. The portal stack — WordPress + BuddyBoss + Moodle + the guildcommerce-core-plugin — is the live operational surface.
  2. ADR-0004 locked in a frontmatter + manifest model where guildcommerce-core-plugin reads YAML frontmatter, builds a manifest, and gates render in the member hub by bp_get_member_type() per Form O. That model was designed for the 22 forms; it generalizes cleanly to documents.
  3. ADR-0007 built a library/ sub-module in the core plugin with replay and resource post types, a unified /library/ archive, and Form O permission gating. The unified library is already the place where members find non-cert learning content.

Continuing to publish the docs as a separate public MkDocs site fragments the experience: a member hits two different reading surfaces depending on which document they want, with two different permission models (the public site has no permission model — everything is world-readable, including operator-side runbooks the Guild does not need to publish). The Operations Lead has decided to consolidate.

The repo itself remains the source of truth and the build pipeline. What changes is the reading surface.

Decision

1. Reading surfaces

The document library is rendered into two authenticated portal surfaces, both backed by the same repo:

Surface Audience Where it lives
Member surface (BuddyBoss section) All authenticated members, any tier guildcommerce.pplx.app — a Document Library section in the BuddyBoss member nav
Hub surface Operators, board, committee chairs, counsel, sysadmin A Hub → Library area on the live WP install (post-staging go-live), behind the same guildcommerce-core-plugin / library permission gate

Both surfaces render the same underlying documents. Per-doc visibility is governed by Form O via frontmatter, not by which surface a reader is on — i.e., a board-only document does not appear on the member surface even though it lives in the same library, because Form O says visible_to: [board, officer, sysadmin, counsel].

2. Public MkDocs site is taken offline (build pipeline retained)

ginalyncox.github.io/ganjier-guild-launch-blueprint/ is retired as a published site. The MkDocs / GitHub Pages workflow is disabled in .github/workflows/. Visitors are redirected (or the site simply 404s — see Implementation).

The PDF build pipeline (.github/pdf/build-list.txt, .github/pdf/build-manifest.py) continues to run on every push to main. It still produces:

  • dist/<path>.pdf for every doc in build-list.txt
  • dist/forms-manifest.json
  • A new dist/library-manifest.json (this ADR; see §3)

Those artifacts are what the portal pulls. The repo stays public on GitHub for transparency (counsel, prospective directors, sister-org peer review) — what stops being public is the rendered reading site.

3. Frontmatter contract for documents (extends ADR-0004)

Every document under the doc-library publishing scope gets YAML frontmatter using the same slugs as Form O. Schema:

---
doc_id: tech-guildcommerce-runbook         # stable slug; matches the doc's path
title: "GuildCommerce Platform Runbook"
category: Tech                              # Governance | Programs | Tech | Finance | Compliance | Decisions | Brand | Marketing | Forms
audience: internal                          # public | internal | restricted (Honey | Mint | Lavender)
status: draft                               # draft | adopted | superseded
visible_to: [operator, board, officer, sysadmin, counsel]
last_reviewed: 2026-05-09
owner_role: sysadmin                        # who keeps it current
related_forms: [G, H, K]                    # optional
related_adrs: [0004, 0007, 0009]           # optional
---

Frontmatter values for audience and visible_to must be consistent with each other and with Form O. CI validates this (deferred check, mirrors ADR-0004's check-form-o-consistency.py).

Docs that should not appear in the portal at all (e.g., a _drafts/ doc, a transient working scratch file) carry status: draft AND are excluded from build-list.txt. The library manifest only includes docs in build-list.txt.

4. Library manifest

.github/pdf/build-manifest.py is extended (or a sibling build-library-manifest.py is added) to emit dist/library-manifest.json:

{
  "schema": "guild-library/v1",
  "generated_at": "2026-05-09T20:00:00Z",
  "docs": [
    {
      "doc_id": "tech-guildcommerce-runbook",
      "title": "GuildCommerce Platform Runbook",
      "category": "Tech",
      "audience": "internal",
      "status": "draft",
      "visible_to": ["operator", "board", "officer", "sysadmin", "counsel"],
      "owner_role": "sysadmin",
      "last_reviewed": "2026-05-09",
      "markdown_url": "https://.../tech/guildcommerce-runbook.md",
      "pdf_url": "https://.../dist/tech/guildcommerce-runbook.pdf",
      "related_forms": ["G", "H", "K"],
      "related_adrs": [4, 7, 9]
    },
    ...
  ]
}

The plugin fetches this manifest the same way ADR-0004 fetches forms-manifest.json — from a release artifact or a checked-in copy under guildcommerce-core-plugin / library / data/.

5. Plugin integration (extends ADR-0007 library module)

guildcommerce-core-plugin / library adds a third post type: doc.

  • One doc post per library-manifest.json entry, written on activation and on a daily cron.
  • On render, the plugin calls bp_get_member_type( $user_id ) and filters by permissions.visible_to — identical to forms.
  • The same /library/ archive page (already built in ADR-0007) gains a "Documents" filter alongside "Replays" and "Resources." All three filter against the same Form O permission model.
  • Per-doc page renders the markdown inline (via the existing markdown-to-HTML pipeline used for gc_form posts) and offers the rendered PDF as a download.

The two reading surfaces (member BuddyBoss + Hub) are different navigation entry points into the same underlying doc post type. Hub readers (operator/board/officer/sysadmin/counsel) see all docs they have permission for; member readers see the subset their member-type permits.

6. What changes in this repo right now

  • Add frontmatter to existing docs that don't have it. Forms already have it. Most other docs do not.
  • Update .github/pdf/build-list.txt semantics: the file becomes the "publish to library" allow-list. Docs not in the list are not in the manifest, regardless of frontmatter.
  • Disable .github/workflows/<mkdocs-publish>.yml (or whichever workflow publishes the public site). The GitHub Pages site stops updating.
  • Replace the framing language on the README and ecosystem-level docs that calls this a "public document library." It's now a "working document repository with PDF + manifest builds" — the reading surface is the portal.

Frontmatter back-fill is incremental; an unframed doc inherits sensible defaults at manifest-build time (audience: internal, visible_to: [member, ganjier, navigator, operator, board, officer, sysadmin, counsel]) so nothing breaks during the transition. The defaults err on the side of "members can read" rather than "members are blocked," consistent with the answer to "who can read the library inside the portal — all authenticated members."

Consequences

Positive:

  • One reading model across forms, replays, resources, and now docs — Form O is the canonical permission source for everything in the library.
  • Operator-side docs (runbooks, deploy notes, instructor pool ops) stop being world-readable. They sit on the Hub surface for the people who need them.
  • Member-facing docs (launch blueprint, glossary, member-survey, FAQ) get a real home in the BuddyBoss surface, in the same nav as their other member tools.
  • Counsel gets a single consistent surface (Hub) instead of "go read the public site for these docs and the private packet for those."
  • The MkDocs / GitHub Pages dependency goes away. One less reading surface to keep brand-consistent.
  • The repo stays open on GitHub for transparency — what's leaving is the styled reading experience, not the source.

Negative / trade-offs:

  • Frontmatter back-fill is real work. Mitigated by the default-permission rule above.
  • Counsel and prospective directors who liked the polished public reading site will need a portal account to read the library. Acceptable — they were already going to need accounts for the rest of the operating ecosystem; the portal supports a counsel member type per Form O.
  • The repo's public README + ecosystem framing language ("working document library, open for review") needs revision. Captured in §6.
  • Documents that were genuinely meant to be public-internet-readable (e.g., a recruiting page) need a different home. Those become content on ganjierguild.com (the new theme), not docs in the library.

Rollout sequencing:

  1. Now (this commit): ADR-0010 lands; frontmatter is added to a first wave of docs (the ones written this session — runbook, learning ops, event runbook, ADR-0009, Instagram spec); manifest builder is sketched; reading surfaces are described.
  2. With staging go-live on Cloudways: the library module's doc post type ships in guildcommerce-core-plugin; the BuddyBoss surface and Hub surface are wired up; first batch of docs is rendering inside the portal.
  3. After portal smoke-test passes: the MkDocs publish workflow is disabled; the public GitHub Pages site is taken offline. The repo + PDF build keeps running.
  4. Ongoing: every new doc carries frontmatter; every PR to build-list.txt is reviewed for correct audience and visible_to; quarterly access review reconciles frontmatter against current Form O assignments.

Cross-references