# Significance of BEHAVIORS.md and PAGE_TOPOLOGY.md in the Research Folder

> Understand the significance of BEHAVIORS.md and PAGE_TOPOLOGY.md. These AI-generated files map page hierarchy and agent behaviors, crucial for accurate website reverse-engineering.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: deep-dive
- Published: 2026-06-23

---

**BEHAVIORS.md and PAGE_TOPOLOGY.md are auto-generated research artifacts that serve as the "behavior bible" and page hierarchy map, enabling AI agents to reverse-engineer target websites with pixel-perfect accuracy.**

In the `JCodesMore/ai-website-cloner-template` repository, the `docs/research/` directory stores critical blueprints produced during the site inspection phase. These markdown files capture the dynamic interactions and structural layout of target websites, providing builder agents with the data needed to reconstruct Next.js applications. Understanding the significance of **BEHAVIORS.md** and **PAGE_TOPOLOGY.md** is essential for customizing the AI-driven cloning workflow.

## What Are BEHAVIORS.md and PAGE_TOPOLOGY.md?

Both files are **generated artifacts** created by the `clone-website` pipeline while reverse-engineering a target site. They provide the static and dynamic blueprints required to rebuild a site in a Next.js codebase.

### BEHAVIORS.md: The Behavior Bible

**BEHAVIORS.md** acts as a comprehensive **"behavior bible"** that documents all interactive states, animations, and event-driven logic exhibited by components on the target site. This includes hover effects, focus states, loading sequences, and error conditions. Builder agents consult this file when generating component code to ensure the rebuilt UI reproduces the original site's dynamic behavior **pixel-perfectly**.

According to the source code in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) at line 166, the command explicitly instructs: *"Save all findings to [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md). This is your behavior bible..."*

### PAGE_TOPOLOGY.md: The Page Hierarchy Map

**PAGE_TOPOLOGY.md** stores a **page-level topology map**—a hierarchical description of inspected pages, their URLs, and relational structure (parent/child relationships, routing patterns, and dynamic segments). Builder agents utilize this map to create appropriate Next.js route files (`app/…/page.tsx`) and organize assets under the `public/` directory.

While this file is created automatically during the inspection phase, its intended structure is documented in the "Phase 3: Layout Architecture" section of [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md).

## How the Research Files Are Generated

The template follows a multi-phase pipeline that produces these artifacts at runtime rather than storing them in version control.

During the inspection phase, the clone-website skill crawls the target site and extracts:
- Component interaction patterns for [`BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/BEHAVIORS.md)
- URL hierarchies and routing structures for [`PAGE_TOPOLOGY.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/PAGE_TOPOLOGY.md)

As implemented in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md), the pipeline saves behavioral findings to [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md), while the topology mapping aligns with the documentation output steps outlined in [`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md).

## Consuming the Research Artifacts in Your Workflow

After a clone run, developers and builder agents parse these files to drive code generation.

### Parsing BEHAVIORS.md for Component Logic

The behavior bible contains structured text describing interaction states. Below is an example of reading and extracting hover specifications:

```typescript
import { readFileSync } from 'node:fs';
import path from 'node:path';

const behaviorsPath = path.resolve('docs/research/BEHAVIORS.md');
const behaviors = readFileSync(behaviorsPath, 'utf-8');

// Extract all hover descriptions
const hoverInfos = behaviors.matchAll(/^##\s+Hover\s*$(.*?)(?=^##|\z)/gms);
for (const [, section] of hoverInfos) {
  console.log('Hover spec →', section.trim());
}

```

### Loading PAGE_TOPOLOGY.md for Route Generation

The topology file typically contains YAML-style structured data describing the page hierarchy:

```typescript
import fs from 'fs';
import yaml from 'js-yaml';

const topology = yaml.load(
  fs.readFileSync('docs/research/PAGE_TOPOLOGY.md', 'utf-8')
);

// Example: Create Next.js routes from topology
for (const page of topology.pages) {
  console.log(`Create route ${page.path} → ${page.title}`);
}

```

## Key Source Files and References

The following files define how these research artifacts are created and consumed:

- **[`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md)** – Command definition specifying that behavioral findings are saved to [`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md) (line 166)
- **[`docs/research/INSPECTION_GUIDE.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/INSPECTION_GUIDE.md)** – Documents Phase 3 (Layout Architecture) and the documentation output steps that generate the topology map
- **[`docs/research/BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/BEHAVIORS.md)** – Target location for the generated behavior bible (created at runtime)
- **[`docs/research/PAGE_TOPOLOGY.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/docs/research/PAGE_TOPOLOGY.md)** – Target location for the generated page topology (created at runtime)

## Summary

- **[`BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/BEHAVIORS.md)** captures *how* components behave, documenting animations, states, and interactions in a "behavior bible" format.
- **[`PAGE_TOPOLOGY.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/PAGE_TOPOLOGY.md)** captures *where* components live, mapping page hierarchies and routing structures.
- Both files are **auto-generated** in `docs/research/` during the clone-website pipeline execution.
- Builder agents consume these artifacts to generate pixel-perfect Next.js components and routes.
- The files are **runtime artifacts** referenced in [`.opencode/commands/clone-website.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.opencode/commands/clone-website.md) and should not be checked into version control.

## Frequently Asked Questions

### Are BEHAVIORS.md and PAGE_TOPOLOGY.md checked into version control?

No. These are **generated artifacts** created automatically when the `clone-website` command runs. They are written to `docs/research/` at runtime and should be added to `.gitignore` since they contain site-specific research data derived from external targets.

### How does BEHAVIORS.md capture complex animation states?

The file documents animation states through structured markdown sections that describe trigger conditions (hover, focus, scroll) and CSS properties or JavaScript event handlers observed during the inspection phase. Builder agents parse these specifications to replicate timing functions, easing curves, and transition states in the generated React components.

### Can I manually edit these files after generation?

Yes. While automatically generated, both files serve as **blueprints** that developers can refine. Editing [`BEHAVIORS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/BEHAVIORS.md) allows you to fine-tune interaction specifications before component generation, while modifying [`PAGE_TOPOLOGY.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/PAGE_TOPOLOGY.md) lets you adjust routing structures or add metadata before the builder agents create the Next.js app directory structure.

### What format does PAGE_TOPOLOGY.md use?

The topology file typically uses **YAML-fronted markdown** or structured markdown with YAML blocks to represent page hierarchies, URLs, and dynamic route segments. This format allows easy parsing by both JavaScript YAML parsers and human readers reviewing the site architecture.