DISCOVERY.md

/goal

You are performing a project discovery and knowledge-base initialization task.

Your first responsibility is to understand the project.

Your second responsibility is to document it.

Do not make feature changes.

Do not make design changes.

Do not modify application behavior.

Your goal is to build and populate the .agents/ knowledge system.

Before doing anything else:

1. Read .agents/INSTRUCTIONS.md
2. Follow every instruction contained within it.
3. Treat the instructions as the governing rules for this task.

---

## Discovery Phase

Perform a complete repository analysis.

Inspect:

* Astro configuration
* Starlight configuration
* All installed integrations
* All installed plugins
* All content collections
* All routes
* All layouts
* All pages
* All components
* All CSS files
* All theme overrides
* All Starlight overrides
* All custom Astro components
* Build and deployment configuration
* Package dependencies
* Existing documentation

Map how the project is structured.

Record findings before making conclusions.

---

## External Research Phase

Research current documentation for:

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

Determine:

* Intended architecture
* Override mechanisms
* Theme customization methods
* Routing behavior
* Content collection behavior
* Best practices
* Upgrade-safe customization strategies

Document any project usage that differs from recommended practices.

Cite sources inside documentation where useful.

---

## Knowledge Base Generation

Populate:

.agents/project-map.md
.agents/architecture.md
.agents/routing.md
.agents/theme-overrides.md
.agents/troubleshooting.md
.agents/conventions.md
.agents/session-notes.md
.agents/decisions.md

Populate using verified findings only.

Do not use placeholders.

If information cannot be verified, explicitly mark:

UNKNOWN - Requires further investigation

---

## CSS Analysis

Inspect every CSS file.

For each CSS override determine:

* What it affects
* Why it exists
* Whether it is documented
* Whether it follows project policy

Document all findings in:

.agents/theme-overrides.md

If an override lacks explanation:

* Infer purpose when evidence exists
* Otherwise mark:
    UNKNOWN PURPOSE

Do not remove anything.

---

## Override Analysis

Identify:

* CSS overrides
* Starlight component overrides
* Astro component overrides
* Theme overrides

For each override document:

* Purpose
* Location
* Scope
* Upgrade impact
* Alternative approaches

---

## Architectural Decision Recovery

Review the repository and attempt to identify historical decisions.

Document:

* Why major structures exist
* Why plugins were selected
* Why overrides exist
* Why routing is organized as it is

Record findings in:

.agents/decisions.md

When reasoning is uncertain:

Mark:

INFERRED - NOT VERIFIED

---

## Gap Analysis

After documentation is complete:

Create a report containing:

1. Missing documentation
2. Potential maintenance risks
3. Undocumented overrides
4. Undocumented components
5. Upgrade risks
6. Technical debt
7. Areas requiring manual review

---

## Final Deliverable

Produce:

1. Populated knowledge-base files.
2. A summary of discoveries.
3. A gap analysis report.
4. A list of recommendations for improving future agent efficiency.

Success is measured by how much knowledge is preserved for future sessions, not by changes made to the website.