RedRoot AI Research

Public-safe research site, Oracle AI CEC workshop catalog, and AI-readable knowledge pack for RedRoot, RedForge, Oracle MAA, DORA, resilience, migration, and planned-maintenance evidence.

This repository is more than a static blog. It is a publication pipeline for sanitized RedRoot and RedForge PoC findings, a curated workshop catalog, a governed Oracle/DORA knowledge base, and a small grounded workshop assistant that only uses approved public catalog data.

What Is In This Repo

• src/content/posts/ - MDX research notes generated from approved RedRoot or RedForge evidence and reviewed before publication.
• src/data/workshops.ts - the source of truth for the FSI DRIL workshop catalog, including agendas, outcomes, evidence language, duration variants, and AI retrieval metadata.
• knowledge/entries/ - structured YAML knowledge entries used to ground Oracle MAA, DORA, RedForge, and workshop terminology.
• docs/knowledge/ - human-readable knowledge notes, governance rules, and editorial guidance.
• src/pages/ai/workshops.json.ts - machine-readable public workshop catalog for the assistant and external retrieval.
• src/pages/ai/workshops.md.ts - Markdown retrieval pack for LLM-oriented clients.
• src/pages/llms.txt.ts - AI resource index for the public site.
• serverless/workshop-assistant-proxy.mjs - optional OpenAI proxy for generated workshop recommendations.
• scripts/ - release, redaction, KB export, link-check, draft-generation, and publication helpers.

Stack

• Astro with TypeScript and MDX.
• Astro content collections for post schema validation.
• Static output for GitHub Pages and OCI Object Storage.
• RSS, sitemap, llms.txt, workshop JSON, and workshop Markdown generation.
• pnpm/Corepack for deterministic installs in CI.
• Public-safe redaction, knowledge-base grounding, and local link checks before release.

Local Development

corepack enable
pnpm install
pnpm run dev

Astro serves the site locally and renders the floating Workshop Assistant. Without a proxy URL, the assistant still works by ranking workshops in the browser from /ai/workshops.json.

Build And Checks

pnpm run check
pnpm run redaction:check
pnpm run build

pnpm run build runs the full release path:

1. Astro type/schema checks.
2. Public-safe redaction scan.
3. Static Astro build.
4. Knowledge-base export to dist/knowledge/.
5. Workshop KB guard validation.
6. Local link check.

Useful focused commands:

pnpm run knowledge:build
pnpm run workshops:kb:guard
pnpm run links:check
pnpm run sla:sanitize

Publication Model

The project treats RedRoot and RedForge evidence as private source material by default. Public pages should contain only reviewed, sanitized findings and approved artifacts.

1. RedRoot or RedForge produces operational report artifacts.
2. A draft MDX post is created from approved metadata and briefing text.
3. The draft starts as status: draft.
4. A reviewer checks public-safety, evidence wording, artifact links, and MAA/DORA claims.
5. CI runs schema checks, redaction checks, build, KB guard, and link checks.
6. Only reviewed published posts that are not private-first render publicly. Private-first posts render only when PUBLIC_PRIVATE_RESEARCH_MODE=true and PUBLIC_WORKSHOP_MODE is not true.

Create a draft from a RedRoot run:

pnpm run draft:from-redroot -- \
  --run-dir /path/to/logs/<run-group>/<run-id> \
  --slug example-redroot-run \
  --title "Example RedRoot Run"

Generated drafts must be edited before publication.

Workshop Catalog

Workshop content is centralized in src/data/workshops.ts. The same data drives:

• /workshops/ and individual workshop pages.
• /ai/workshops.json for structured assistant retrieval.
• /ai/workshops.md for Markdown retrieval.
• /llms.txt for AI clients.
• The floating Workshop Assistant.

Set PUBLIC_WORKSHOP_MODE=true for public deployments. Public mode strips richer local-only material such as private facilitation details and related RedForge report links from the AI catalog. GitHub Pages also runs pnpm run workshops:public:guard after the public build so generated workshop pages remain overview-only and never include fullscreen presentation controls or hands-on runner markup.

Knowledge Base

Structured KB entries in knowledge/entries/ are exported during build to:

• dist/knowledge/redroot-kb.json
• dist/knowledge/redroot-kb.md

The workshop KB guard compares workshop language against approved KB terminology and source boundaries. Oracle solution terms must be grounded in trusted Oracle sources. Regulatory framing can use official regulatory or supervisory sources. RedRoot and RedForge evidence language must stay evidence-bound and must not imply Oracle certification or formal attestation.

Workshop Assistant Proxy

The floating Workshop Assistant works without a backend by using the public /ai/workshops.json matcher in the browser. To enable generated recommendations, build the blog with:

PUBLIC_WORKSHOP_ASSISTANT_PROXY_URL=https://<proxy-host>/workshop-assistant pnpm run build

Deploy serverless/workshop-assistant-proxy.mjs as the external OpenAI proxy or run it directly with Node:

OPENAI_API_KEY=<key> \
WORKSHOP_CATALOG_URL=https://<site>/ai/workshops.json \
ALLOWED_ORIGINS=https://<site> \
node serverless/workshop-assistant-proxy.mjs

Opening http://localhost:8787/workshop-assistant in a browser returns proxy health and configuration status. Assistant answers require a POST request from the widget and both OPENAI_API_KEY and WORKSHOP_CATALOG_URL configured.

The proxy fetches the public workshop catalog, retrieves the best public snippets locally, calls the OpenAI Responses API with store: false, and returns structured JSON for the widget. Keep OPENAI_API_KEY server-side only; the static blog only receives PUBLIC_WORKSHOP_ASSISTANT_PROXY_URL.

The same proxy is Cloudflare Worker-compatible through wrangler.toml. The Worker still needs OPENAI_API_KEY set as a secret before it can answer assistant requests.

Publish To OCI Object Storage

The Object Storage publication path is static. Build it with the Object Storage base path and the deployed proxy URL, then upload dist/:

SITE="https://objectstorage.<region>.oraclecloud.com" \
BASE_PATH="/n/oscemea001/b/bucket-RedForge-AIPoC/o/redroot-ai-research" \
PUBLIC_WORKSHOP_MODE="true" \
PUBLIC_WORKSHOP_ASSISTANT_PROXY_URL="https://<proxy-host>/workshop-assistant" \
pnpm run build

pnpm run publish:object-storage

For a pre-authenticated Object Storage URL, include the PAR path in both the Astro build base path and the publisher validation base path. Otherwise the page HTML may load through /p/<token>/..., while stylesheets, images, and internal links fall back to unauthenticated /n/... URLs.

SITE="https://objectstorage.<region>.oraclecloud.com" \
BASE_PATH="/p/<par-token>/n/oscemea001/b/<bucket>/o/redroot-ai-research" \
PUBLIC_WORKSHOP_MODE="true" \
PUBLIC_WORKSHOP_ASSISTANT_PROXY_URL="https://<proxy-host>/workshop-assistant" \
pnpm run build

pnpm run publish:object-storage -- \
  --region <region> \
  --bucket <bucket> \
  --access-base-path "/p/<par-token>/n/oscemea001/b/<bucket>/o/redroot-ai-research"

Without PUBLIC_WORKSHOP_ASSISTANT_PROXY_URL, the Object Storage site still works but uses the browser-only public catalog matcher.

Private-first research posts require an explicit private build flag:

PUBLIC_PRIVATE_RESEARCH_MODE="true" pnpm run build

GitHub Pages

The deploy workflow computes the Pages base path from GITHUB_REPOSITORY. For a project repository named redroot-ai-research, the public URL will be:

https://<github-owner>.github.io/redroot-ai-research/

Set SITE in the workflow only if you move to a custom domain or a user/org Pages repository.

Public-Safe Style Notes

• Keep the redrootRunId frontmatter so the Run ID metadata box renders, but avoid raw run IDs in titles, descriptions, and body prose.
• Include an Outage And Workload Impact section for resilience posts, even when the result is no measured outage.
• Add the Oracle AI Customer Excellence Center contact line in publication notes when a full-report review is available.
• Use generic labels in public-safe diagrams; prefer PDB1, PDB2, PDB3, and PDB4 over private PDB names or generic lane names when describing replicated PDB paths.
• Scope MAA language carefully: describe RedRoot public-safe PoC evidence and assessed posture, not Oracle certification or formal attestation.
• Do not publish raw logs, OCIDs, private IP addresses, internal hostnames, tenant names, secrets, tokens, raw operational paths, or private evidence filenames.

Create The GitHub Repository

When a GitHub token is available, create the public repository and push the local main branch with:

GITHUB_TOKEN=<token> pnpm run repo:create -- --owner <github-owner>

Use --org <github-org> instead of --owner when the repo should belong to an organization.