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

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 at line 166, the command explicitly instructs: "Save all findings to 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.

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
• URL hierarchies and routing structures for PAGE_TOPOLOGY.md

As implemented in .opencode/commands/clone-website.md, the pipeline saves behavioral findings to docs/research/BEHAVIORS.md, while the topology mapping aligns with the documentation output steps outlined in 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:

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:

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 – Command definition specifying that behavioral findings are saved to docs/research/BEHAVIORS.md (line 166)
• docs/research/INSPECTION_GUIDE.md – Documents Phase 3 (Layout Architecture) and the documentation output steps that generate the topology map
• docs/research/BEHAVIORS.md – Target location for the generated behavior bible (created at runtime)
• docs/research/PAGE_TOPOLOGY.md – Target location for the generated page topology (created at runtime)

Summary

• BEHAVIORS.md captures how components behave, documenting animations, states, and interactions in a "behavior bible" format.
• 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 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 allows you to fine-tune interaction specifications before component generation, while modifying 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}