From 3388dc5c9692647a02766f63aa08559e3b816539 Mon Sep 17 00:00:00 2001 From: Antony Natale Date: Wed, 10 Jun 2026 15:48:58 -0400 Subject: [PATCH 1/2] updates contributing guide and claude/agent files for the new internal docs information --- AGENTS.md | 12 +++++++----- CLAUDE.md | 9 ++++----- CONTRIBUTING.md | 7 ++++--- 3 files changed, 15 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 405a67f..eac0048 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -141,13 +141,15 @@ This system has three cooperating parts: When editing client-package pages, the API surface is defined entirely in YAML frontmatter, not in the Markdown body. The specification uses JavaScript conventions (`camelCase`) as canonical; implementations transform to language-specific conventions. -## Fork and Overlay Architecture +## Internal Documentation -This repository is designed to be forked for internal documentation. The `config-overlay.mjs` file provides two hook functions: -- `applyTopLevelOverlay(config)` -- modifies top-level Astro config (site URL, base path, integrations) -- `applyStarlightOverlay(starlightConfig)` -- modifies Starlight config (sidebar entries, plugins) +This repository contains the public Kessel documentation. Supplemental internal documentation -- covering Red Hat-specific onboarding, hosted environment configuration, operational runbooks, and monitoring -- is maintained in a separate repository and published to InScope (Red Hat's internal developer portal, accessible via VPN). -**Critical rule**: In the public repository, changes to `config-overlay.mjs` and `astro.config.mjs` must be made carefully as they affect internal forks. The warning in `config-overlay.mjs` is explicit: modifications may break internal mirroring. In a fork, you MUST NOT modify files that originate from the public repository. +Content belongs in the right place: +- **Public docs (this repo)**: Integration guides, SDK docs, API reference, concepts, and anything relevant to all Kessel users. +- **Internal docs (InScope)**: Red Hat-specific configuration, credentials setup, ephemeral testing, hosted architecture, runbooks, and monitoring procedures. + +Do not add Red Hat-specific operational content to this repository. ## Cross-Cutting Conventions diff --git a/CLAUDE.md b/CLAUDE.md index 3fadaa4..7e75f56 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -21,11 +21,10 @@ This repository uses `rh-multi-pre-commit` for Red Hat security scanning. The ho ## Claude Code Behavioral Preferences -### File modification priority -- **CRITICAL**: This repository has a fork/overlay architecture for internal documentation -- Modifications to `config-overlay.mjs` and `astro.config.mjs` affect internal forks - exercise extreme caution -- The warning in `config-overlay.mjs` is explicit: modifications may break internal mirroring -- When making changes to these files, follow up immediately to resolve conflicts in forks +### Content placement +- This repository is for **public** Kessel documentation only +- Internal Red Hat-specific content (onboarding, hosted config, runbooks, monitoring) belongs in the separate internal docs repo published to InScope +- Do not add Red Hat-specific operational content to this repository ### Content creation - Use `.mdx` for pages needing Astro components (`Aside`, `Tabs`, `CodeExamples`, etc.) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c91a29d..ec7ed25 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,7 +19,6 @@ src/ docs/ # AI agent guidelines public/ # Static assets (favicon) astro.config.mjs # Astro and Starlight configuration -config-overlay.mjs # Fork/overlay hooks for internal documentation ``` Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. @@ -44,6 +43,8 @@ See [Writing documentation](src/content/docs/contributing/documentation.mdx). ## Internal documentation -This repository can be forked to augment with internal deployment documentation. [config-overlay.mjs](config-overlay.mjs) is designed to be overridden by forks in order to modify the sidebar for the inclusion of e.g. internal documentation. +This repository contains the public Kessel documentation. Supplemental internal documentation covering Red Hat-specific onboarding, hosted environment configuration, operational runbooks, and monitoring, is maintained separately and published to InScope (Red Hat's internal developer portal, accessible via VPN). The internal docs expand on the public content with details that cannot be published externally. -Keep this in mind when making changes to this repository–note which repository you are working in. Inside the fork, you MUST not modify files which come from the public docs repository. In the public docs repository, care must be taken when modifying explicitly shared and overriden files, like `config-overlay.mjs`. +When contributing, keep content in the right place: +- **Public docs (this repo)**: Integration guides, SDK docs, API reference, concepts, and anything relevant to all Kessel users. +- **Internal docs (InScope)**: Red Hat-specific configuration, credentials setup, ephemeral testing, hosted architecture, runbooks, and monitoring procedures. From efa430f2b9c320e2ee966a9b96c8868cfa3c6d28 Mon Sep 17 00:00:00 2001 From: Antony Natale Date: Wed, 10 Jun 2026 15:49:57 -0400 Subject: [PATCH 2/2] removes config.overlay.js --- config-overlay.mjs | 36 ------------------------------------ 1 file changed, 36 deletions(-) delete mode 100644 config-overlay.mjs diff --git a/config-overlay.mjs b/config-overlay.mjs deleted file mode 100644 index 90ed9b5..0000000 --- a/config-overlay.mjs +++ /dev/null @@ -1,36 +0,0 @@ -// Configuration overlay for extending Astro and Starlight configs -// -// This file provides two targeted overlay functions: -// 1. applyTopLevelOverlay - modifies top-level Astro configuration (site, base, integrations, etc.) -// 2. applyStarlightOverlay - modifies Starlight configuration (sidebar, title, plugins, etc.) -// - -// **WARNING** MODIFICATIONS TO THIS FILE MAY BREAK INTERNAL MIRRORING. -// It is allowed to modify this file, but be sure to quickly follow up -// by manually resolving conflicts in the fork. - -/** - * Apply overlays to top-level Astro configuration - * @param {Object} config - The base Astro configuration object - * @returns {Object} - The modified configuration - */ -export function applyTopLevelOverlay(config) { - return config; -} - -/** - * Apply overlays to Starlight configuration - * @param {Object} starlightConfig - The base Starlight configuration object - * @returns {Object} - The modified configuration - */ -export function applyStarlightOverlay(starlightConfig) { - starlightConfig.sidebar.push({ - label: "For Red Hatters", - link: "./for-red-hatters/", - attrs: { - class: "red-hat", - }, - }) - - return starlightConfig; -}