INSTRUCTIONS.md

# .agents/INSTRUCTIONS.md

# Project Timezone

For all dates, timestamps, changelog entries, session notes, troubleshooting records, and generated documentation:

Use America/New_York as the authoritative project timezone.

Do not use UTC.

Do not infer timezone from the execution environment.

If a timestamp is required, generate it using America/New_York local time.

# Purpose

You are working within a project that maintains a persistent agent knowledge system.

Before making changes, debugging issues, proposing architecture changes, or implementing features, you must consult the project knowledge base and use existing project knowledge whenever possible.

The goal is to:

- Reduce repeated repository exploration
- Reduce repeated debugging of solved issues
- Preserve architectural knowledge between sessions
- Minimize token consumption caused by rediscovery
- Create a single source of truth for project structure and decisions
- Leave the project smarter than you found it

---

# Required Directory Structure

```
.agents/
├── INSTRUCTIONS.md
├── project-map.md
├── architecture.md
├── routing.md
├── theme-overrides.md
├── troubleshooting.md
├── conventions.md
├── session-notes.md
└── decisions.md
```

---

# Agent Startup Requirements

Before performing any task, read:

1. .agents/INSTRUCTIONS.md
2. .agents/project-map.md
3. .agents/troubleshooting.md

Additionally read:

- routing.md when modifying navigation, content, docs, blog, or pages
- theme-overrides.md when modifying CSS or appearance
- architecture.md when modifying layouts, components, plugins, or integrations
- conventions.md when creating new content or code
- decisions.md when evaluating alternatives or proposing architecture changes

Do not rediscover information already documented.

---

# Knowledge Base Creation Requirements

Populate all knowledge-base documents using actual repository inspection.

Do not create placeholders.

Do not invent information.

When information cannot be verified, document:

UNKNOWN - Requires repository inspection

---

# README Maintenance Policy

The repository README.md is the primary entry point for both humans and agents.

README.md should remain an accurate high-level description of the current project state.

Agents should treat README.md as living documentation rather than a one-time setup file.

## Maintain README When

Review README.md whenever:

* Project architecture changes

* Routing changes

* Deployment changes

* Theme or plugin choices change

* Major project goals change

* New maintainer onboarding reveals documentation gaps

* Significant owner decisions affect project direction

## README Responsibilities

README.md should describe:

* What the project is

* Why the project exists

* Major technologies in use

* Current architecture

* Content organization

* Deployment model

* Agent knowledge-base entry points

* Current project direction

* Important active limitations or known issues

README.md should not attempt to duplicate the full `.agents` knowledge base.

Instead, README.md should guide maintainers toward the relevant `.agents` documents.

## Removing Stale Information

Agents should remove or update README content when it is no longer accurate.

Do not preserve outdated information solely for historical purposes.

Historical context belongs in:

* decisions.md

* session-notes.md

* troubleshooting.md

README.md should prioritize current truth over project history.

## Owner Intent Preservation

When the project owner makes explicit decisions regarding:

* Site architecture

* Navigation structure

* Branding

* Design philosophy

* Documentation organization

* Deployment strategy

* Theme selection

those decisions should be reflected in README.md.

README.md should describe the intended direction of the project, not merely its current implementation.

## New Maintainer Test

Periodically evaluate README.md using this question:

"If a new maintainer read only README.md, would they understand what this project is, how it is organized, where to start, and where to find deeper documentation?"

If the answer is no, improve README.md.

## README Update Rule

Whenever a significant project discovery or owner decision is recorded in:

* decisions.md

* architecture.md

* routing.md

consider whether README.md should also be updated.

README.md should evolve alongside the project.

---

# Project Map Requirements

Document:

- Astro version
- Starlight configuration
- Installed integrations
- Installed plugins
- Route structure
- Content collections
- CSS entry points
- Theme override locations
- Layout override locations
- Important pages
- Important components
- Build and deployment information

Use relative paths only.

Never store machine-specific absolute paths.

---

# Architecture Documentation

Document:

- Major layouts
- Component hierarchy
- Plugin interactions
- Override mechanisms
- Content flow
- Build pipeline
- Theme inheritance chain

Especially document:

- Astro
- Starlight
- starlight-blog
- starlight-theme-terminal

---

# Theme Override Documentation

For every intentional override document:

- Purpose
- File location
- Affected component
- Original behavior
- New behavior
- Known side effects

---

# CSS Documentation Standard

All non-trivial CSS overrides must contain adjacent documentation comments.

Comments should explain:

- What is being overridden
- Why the override exists
- What bug, conflict, or requirement caused it
- Known side effects
- Upgrade considerations

Comments should focus on WHY rather than WHAT.

Future maintainers can read CSS.

Future maintainers cannot read history.

Use this template:

```
/*
Override: <short name>

Applies To:
<component or page>

Reason:
<why the override exists>

Reference:
<troubleshooting.md section or decision>

Last Verified:
<date>

Notes:
<any upgrade concerns>
*/
```

---

# CSS Override Philosophy

Prefer solutions in the following order:

1. Local CSS overrides
2. Theme-level overrides
3. Theme source modifications
4. Starlight component overrides
5. Astro/Starlight source modifications

The objective is to maximize upgrade compatibility.

---

# Terminal Theme Exception

The terminal theme is considered part of the project's customization layer.

Modifying starlight-theme-terminal is acceptable when:

- A CSS override is impractical
- A theme-level change is significantly cleaner
- The modification improves maintainability

Whenever modifying terminal theme files:

- Document the reason
- Document affected files
- Document upgrade impact
- Update theme-overrides.md
- Update session-notes.md

---

# Before Modifying Framework Files

Before changing Astro or Starlight source files:

1. Determine whether a CSS override can solve the issue
2. Determine whether a component override can solve the issue
3. Determine whether a theme-level modification can solve the issue
4. Document why those approaches are insufficient

Only then should framework files be modified.

Document the decision in decisions.md.

---

# Override Preservation Policy

Existing overrides should be treated as intentional project knowledge.

Before removing, replacing, bypassing, or simplifying an override:

1. Determine why the override exists
2. Search:

   - theme-overrides.md

   - troubleshooting.md

   - decisions.md

   - session-notes.md
3. Verify the original issue no longer exists
4. Document the reason for removal
5. Update relevant knowledge-base files

Never remove an override solely because its purpose is not immediately obvious.

Assume overrides exist for a reason until proven otherwise.

---

# Evidence-Based Debugging Policy

Agents should prioritize evidence gathering over speculative fixes.

Before implementing a fix:

1. Inspect the rendered output
2. Inspect generated DOM
3. Inspect pseudo-elements
4. Inspect computed styles
5. Identify the active selector
6. Identify the source stylesheet
7. Verify ownership
8. Then implement a fix

Avoid repeated speculative edits without identifying the active source of behavior.

The goal is to minimize token consumption caused by trial-and-error debugging.

---

# CSS Debugging Workflow

Before changing CSS:

1. Inspect rendered DOM
2. Inspect pseudo-elements
3. Inspect computed styles
4. Identify exact source selector
5. Identify source stylesheet
6. Verify ownership
7. Apply the minimal override necessary
8. Verify rendered result

Do not repeatedly guess CSS changes without identifying the active selector.

---

# Layout Debugging Workflow

Before modifying layouts:

1. Identify component source
2. Trace ownership chain
3. Trace route generation
4. Verify theme/plugin involvement
5. Then modify files

---

# Plugin Debugging Workflow

Before modifying plugin behavior:

1. Identify responsible plugin
2. Review plugin documentation
3. Review existing overrides
4. Inspect generated output
5. Then modify implementation

---

# Troubleshooting Database Requirements

Every resolved issue should contain:

- Symptom
- Root Cause
- Resolution
- Verification Method
- Files Changed

Must include known issues such as:

## Blog Tag Square Artifact

Symptom:
Green square displayed before blog tags.

Root Cause:
starlight-theme-terminal markdown list styling injected:

.sl-markdown-content ul:not(:where(.sl-steps, .not-content *)) > li::before

Resolution:
Disable the pseudo-element for tag list items containing direct /blog/tags/ links.

Verification:
Inspect DOM and confirm the tag list no longer renders the li::before marker.

## Header Customization Conflict

Symptom:
Terminal theme warning regarding Header override.

Root Cause:
Terminal theme provides its own Header implementation.

Resolution:
Extend or wrap the terminal Header implementation rather than replacing it outright.

## Historical Evidence

When practical, include:

* Relevant commits
* Relevant pull requests
* Relevant files
* Relevant documentation

to support troubleshooting entries.

---

# Decisions Log Requirements

Maintain decisions.md.

For every major architectural decision record:

- Date
- Decision
- Alternatives considered
- Reasoning
- Outcome

Prevent future sessions from repeatedly revisiting settled decisions.

---

# Session Notes Requirements

Maintain append-only session notes.

Each entry should contain:

- Date
- Objective
- Problem
- Root Cause
- Resolution
- Files Changed
- Follow-up Work

---

# Conventions Documentation

Document:

- Naming conventions
- File organization rules
- CSS conventions
- Override conventions
- Content conventions
- Markdown conventions

Future agents should follow documented conventions rather than inventing new ones.

---

# Knowledge Maintenance Rules

After every successful fix:

1. Update troubleshooting.md
2. Update theme-overrides.md if styling changed
3. Update architecture.md if structure changed
4. Add a session-notes entry
5. Record important discoveries

Knowledge capture is required work, not optional work.

---

# Future Agent Efficiency

- Always read `.agents/INSTRUCTIONS.md`, `.agents/project-map.md`, and `.agents/troubleshooting.md` before working.
- For routing/content changes, read `.agents/routing.md` first.
- For CSS/theme changes, read `.agents/theme-overrides.md` first and inspect the rendered DOM before editing.
- For Header/Footer/plugin work, read `.agents/architecture.md` and `.agents/decisions.md` first.
- Run `npm run build` after meaningful changes; compare warnings against `troubleshooting.md`.
- For CSS-sensitive verification, use freshly generated output or restart the dev server before trusting rendered CSS. Past work found `npm run dev` did not always regenerate CSS changes reliably.
- When serving `dist/` with a manually started static server, verify the server after launch with actual HTTP requests to `/` and at least one nested route such as `/docs/`. Do not treat a background process start as proof the site remains available. In sandboxed sessions, background servers may be cleaned up after the shell command exits; if immediate checks pass but later requests are refused, request approval to start the server outside the sandbox and verify again after a short delay.
- When the owner needs to see the custom `404.html` through an actual missing URL, do not use plain `python -m http.server`: it returns Python's default directory 404 instead of the built Astro page. Start a small `SimpleHTTPRequestHandler` subclass from `dist/` that overrides `send_error(404)` to return `404.html` while preserving HTTP status `404`.
- Persistent preview servers should be started outside the sandbox with `require_escalated`; sandboxed `Start-Process` launches can exit or be cleaned up even when the command appears to start.
- After starting a preview server, verify persistence with `Get-NetTCPConnection -LocalPort <port>` and verify missing-route behavior with `curl.exe`, not only `Invoke-WebRequest`. `Invoke-WebRequest` throws for intentional 404 responses, which can make verification look failed even when the custom 404 server is running correctly.
- Update `.agents` during the same session as any fix so future agents do not repeat discovery.
- Session notes are temporary working memory. Once an issue is resolved, its final conclusions must be migrated into the appropriate architectural document and removed from session-notes.md.

---

# Success Criteria

A brand-new agent should be able to:

- Understand project architecture
- Understand routing
- Understand customizations
- Understand theme behavior
- Understand previously solved bugs
- Understand project conventions
- Understand prior architectural decisions

without rediscovering information from scratch.

---

# Task Completion Metrics

Report any available metrics, including:

- Duration
- Files inspected
- Knowledge-base files updated
- Documentation files created
- Application files modified
- External sources consulted
- Available runtime metrics

Only report metrics actually provided by the runtime.

Do not estimate unavailable metrics.