CLAUDE.md¶

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Read Before Writing Content (Mandatory)¶

Before creating or editing any tool folder or knowledge-base page, read:

1. plan/README.md: index of plans and their status.
2. plan/standards/: the writing standard, the tool folder blueprint, and the definition of done. These override any older page in this repository.
3. The plan for the tool being written (for example plan/linux/), including manifest.yml and checklist.md.

Git rule: commit locally only. Never push, never open pull requests, and never add AI attribution lines (Co-Authored-By, "Generated with") to commits or pull requests. The owner pushes and merges.

Older Nectar pages are not a style reference. When the work changes the plan, update plan.md, manifest.yml and decisions.md in the same commit, and regenerate the checklist with python scripts/gen-checklist.py plan/<tool>.

Notes Conventions¶

These rules apply to every tool folder (Linux is the reference implementation in technical-grounding/linux/). The full text is in plan/standards/.

• Authority: the writing standard follows the persona post at https://blog.ibtisam-iq.com/my-core-ai-engineering-persona/, then runbook and blog practice, then Diátaxis and the Google developer documentation style guide.
• Prose: no em or en dashes, no spaced hyphens, no banned vocabulary, paragraphs of three sentences at most, declarative third person in topic files, imperative steps only in labs. Never invent experience.
• Layout: four layers per tool folder (Learn modules, Revise reference, Interview rounds and scenarios, Practice labs), as described in plan/standards/tool-folder-blueprint.md.
• Templates: templates/topic.md, templates/module-readme.md and templates/scenario.md. Every topic declares **Track:** ... · **Interview weight:** ... and keeps its facts and L1 checkpoints inside snippet markers.
• Output: bash blocks without prompts; real captured output only, in a text block after the line Output:; a capture footer on every page with output.
• Tabs: labels are exactly === "RHEL / Rocky" and === "Ubuntu / Debian", used only where commands or output differ.
• Interview questions: L1 screening, L2 hands-on, L3 troubleshooting, L4 internals, answered as Say first, Proof, Follow-up. Trivia becomes a Must-Know Facts row, not a question.
• Checks before every commit: python scripts/lint-prose.py <folder> and python scripts/audit-tool.py --manifest plan/<tool>/manifest.yml --scope <batch> --build, both with zero failures.

1️⃣ Repository Overview¶

Nectar is a personal engineering knowledge base stored as Markdown and configuration files in a single GitHub repository. It is not a compiled application – rather, it is a collection of documentation, configuration snippets, and reference material that together generate a static documentation site at https://nectar.ibtisam-iq.com.

The source files are organized by domain, including:

2️⃣ Common Development Commands¶

Tip – All commands should be run from the repository root (/Users/ibtisam-iq/gitHub/nectar).

Running Bash Commands in Claude Code¶

If you want to execute any of the commands inside this chat, prefix the command with an exclamation mark:

! mkdocs serve -a 0.0.0.0:8000

Claude Code will run it in its sandbox and return the output.

3️⃣ High‑Level Architecture & Structure¶

3.1 Core Files¶

• mkdocs.yml – Central configuration for the MkDocs site (theme, plugins, extensions, navigation, and build options).
• .github/workflows/pages.yml – CI pipeline that builds, validates, previews, and deploys the documentation site.
• requirements.txt – Pin‑versions of MkDocs and its plugins.
• README.md – High‑level introduction, including a Mermaid diagram that shows how Nectar fits into the author’s broader engineering system.
• index.md – Root landing page of the generated documentation site.

3.2 Documentation Domains¶

3.3 CI/CD Pipeline¶

The repository contains a single GitHub Actions workflow (.github/workflows/pages.yml) that defines three jobs:

The workflow uses minimal permissions (contents: read for the build job, contents: write for preview/deploy) and includes concurrency protection to avoid overlapping deployments.

4️⃣ Important Files & Directories (quick reference)¶

• README.md – Introductory overview and system diagram.
• mkdocs.yml – Full MkDocs configuration.
• .github/workflows/pages.yml – CI/CD pipeline definition.
• requirements.txt – Dependency versions.
• index.md – Home page of the generated site.
• cloud-infrastructure/ – Cloud‑specific guides (AWS, Cloudflare, etc.).
• containers-orchestration/kubernetes/ – Comprehensive Kubernetes documentation set.
• delivery/ – CI/CD tooling notes (ArgoCD, Jenkins, Nexus, SonarQube).
• operations/ – Operational runbooks (Wireguard, CI stack).

5️⃣ Development Workflow¶

1. Create a feature branch
   

   git checkout -b feature/<short‑slug>
   

2. Edit Markdown files – Keep line length consistent with existing files. Add new documentation or update existing content.
3. Preview locally
   

   mkdocs serve -a 0.0.0.0:8000
   

   The site reloads automatically on each save.
4. Build the static site
   

   mkdocs build
   

5. Validate changes
6. Run lychee ./site/**/*.html to catch broken internal links.
7. Optionally run trivy fs . if new binaries were added.
8. Commit and push
   

   git add .
   git commit -m "feat: add <brief description>"
   git push origin feature/<short‑slug>
   

9. Open a Pull Request – CI will automatically build the docs, run link checking, and create a preview deployment. The PR comment will contain the preview URL.
10. Merge – After approval, merging to main triggers the final deploy job that publishes the updated site to GitHub Pages.

6️⃣ Special Configuration Notes¶

7️⃣ Quick Reference Cheat‑Sheet (Copy‑Paste)¶

# 1️⃣ Bootstrap a dev environment
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2️⃣ Serve locally with live reload
mkdocs serve -a 0.0.0.0:8000

# 3️⃣ Build static site (used by CI)
mkdocs build

# 4️⃣ Check for broken links locally (after a build)
lychee ./site/**/*.html

# 5️⃣ Run security scan on bundled assets
trivy fs .

# 6️⃣ Simulate GitHub Action locally (requires `act`)
act -j build   # runs the “build” job from .github/workflows/pages.yml

8️⃣ Goal for Future Claude Code Sessions¶

When Claude Code is invoked in this repository, it should:

1. Emphasize MkDocs‑centric commands (mkdocs serve, mkdocs build).
2. Reference the navigation hierarchy defined by .pages when suggesting where to place new documentation.
3. Leverage the CI pipeline – e.g., remind users that PRs get automatic preview URLs and that link checking runs on every push.
4. Avoid touching autogenerated files (site/, *.pages that already exist) unless explicitly asked to restructure navigation.
5. Use README.md and mkdocs.yml as the single source of truth for site‑wide metadata (site name, URL, theme, analytics).

End of CLAUDE.md