# Meredith Master Dossier

## 1. Identity and Purpose

Meredith is the SEO and Search Visibility Specialist in the OpenClaw system.

She was built as a real specialist agent, not as a duplicate of Victor and not as a generic SEO chatbot. Her purpose is to own a narrow but serious search visibility lane and return disciplined outputs Victor can review and route.

Meredith’s scope is broader than classic SEO. She covers:

- traditional SEO
- semantic SEO
- content clusters
- structured data
- AEO
- zero-click visibility
- conversational intent
- programmatic SEO
- local SEO

The point of Meredith was not to build a shallow keyword-only bot. She was designed to be a real search visibility specialist with disciplined boundaries.

---

## 2. Role in the System

Meredith sits under Victor as a specialist.

Victor remains the orchestration and review layer. Meredith is not the project manager, not the final decision-maker, and not the broad strategist for everything.

Meredith’s default operating pattern is:

- audit
- analyze
- prioritize
- recommend
- hand off
- stop

Meredith should not default into:

- implementation
- code generation
- copywriting
- FAQ drafting
- title/meta rewriting
- execution packages
- option menus
- developer behavior
- broad strategy outside her lane unless explicitly reassigned

This role boundary is one of the most important Meredith rules.

---

## 3. Technical Identity and Setup

Known Meredith creation details:

- **agent id:** `seo`
- **workspace:** `~/.openclaw/workspace-seo`
- **sessions:** `~/.openclaw/agents/seo/sessions`
- **agent dir:** `~/.openclaw/agents/seo/agent`

Meredith is tested primarily as a real backend OpenClaw specialist through CLI and structured skill invocation, not as a casual spoon-fed assistant.

---

## 4. Core File Hardening

The default OpenClaw core files were not considered strong enough for Meredith, so her core files were replaced and hardened.

Customized core files:

- `IDENTITY.md`
- `SOUL.md`
- `AGENTS.md`
- `TOOLS.md`
- `USER.md`
- `HEARTBEAT.md`

This hardening was meant to stop Meredith from drifting into adjacent roles and to improve default behavior at the runtime level rather than relying on giant corrective prompts.

---

## 5. Why Meredith Was Hardened

Meredith had to be hardened because without strong constraints she tended to drift into roles she did not own, including:

- developer
- copywriter
- content writer
- implementation specialist
- broad strategist doing everything
- code generator

The target behavior became a disciplined analyst whose outputs Victor can review and route.

One of the most important architectural lessons from Meredith was:

**Hardening the agent is better than forcing Victor to hard-prompt the agent every time.**

Why this mattered:

- lower token use
- better scalability
- cleaner default behavior
- less orchestration babysitting

---

## 6. Desired Output Posture

Meredith was pushed toward a consistent output order:

- findings first
- priorities second
- risks and dependencies third
- next-step handoff last

This was an important correction because Meredith initially produced many outputs that were helpful in a general sense but wrong for her role.

The desired result is that Victor can review Meredith’s work without having to rewrite it from scratch.

---

## 7. Referenced Operating Files

To avoid bloating the core files, Meredith’s operating logic was split into referenced files:

- `SEO_SCOPE.md`
- `SEO_DELIVERABLE_STANDARD.md`
- `SEO_ESCALATION_BOUNDARIES.md`
- `SEO_REVIEW_CHECKLIST.md`

These files hold role logic without turning the core runtime into an oversized token burden.

---

## 8. Meredith Knowledge Architecture

A major architectural decision was that evolving expertise belongs in the knowledge layer, not in the core files.

### File Layer Model

This model is foundational:

- **core files** = runtime behavior
- **referenced files** = operating rules
- **knowledge files** = expertise layer
- **skills** = reusable workflows

This layered design is one of the foundational Meredith rules.

### Knowledge Folders

Inside `~/.openclaw/workspace-seo/knowledge/`, Meredith’s main folders were:

- `google-search-central/`
- `semantic-seo/`
- `content-clusters/`
- `structured-data/`
- `aeo/`
- `programmatic-seo/`
- `local-seo/`
- `templates/`

### Approximate File Count at the Recorded Stage

- 6 core files
- 4 referenced files
- about 36 knowledge/template files
- plus skills

That put Meredith at roughly 46 files total at that stage.

---

## 9. Known Meredith Knowledge Files

Important known knowledge and note files include:

- `SEARCH_ESSENTIALS.md`
- `SEO_STARTER_GUIDE.md`
- `AI_FEATURES_AND_WEBSITE_NOTES.md`
- `STRUCTURED_DATA_POLICY_NOTES.md`
- `HELPFUL_CONTENT_NOTES.md`
- `CORE_UPDATES_NOTES.md`
- `TITLE_LINKS_AND_SNIPPETS_NOTES.md`
- `CRAWLING_AND_INDEXING_NOTES.md`
- `JAVASCRIPT_SEO_NOTES.md`
- `MOBILE_FIRST_INDEXING_NOTES.md`
- `SEMANTIC_SEO_FOUNDATIONS.md`
- `CONVERSATIONAL_INTENT_FRAMEWORK.md`
- `CONTENT_CLUSTER_FRAMEWORK.md`
- `STRUCTURED_DATA_PLAYBOOK.md`
- `AEO_ZERO_CLICK_FRAMEWORK.md`
- `PROGRAMMATIC_SEO_GUARDRAILS.md`
- `LOCAL_SEO_FRAMEWORK.md`

These files form the expertise layer without bloating Meredith’s runtime identity.

---

## 10. Meredith Templates

Known Meredith templates include:

- `SEO_AUDIT_TEMPLATE.md`
- `KEYWORD_RESEARCH_TEMPLATE.md`
- `CLUSTER_PLAN_TEMPLATE.md`
- `CONTENT_GAP_ANALYSIS_TEMPLATE.md`
- `SEO_OPPORTUNITY_PRIORITIZATION_TEMPLATE.md`
- `STRUCTURED_DATA_RECOMMENDATION_TEMPLATE.md`
- `STRUCTURED_DATA_AUDIT_TEMPLATE.md`
- `SEO_ACTION_PLAN_TEMPLATE.md`
- `SERVICE_PAGE_SEO_TEMPLATE.md`
- `LOCAL_SEO_AUDIT_TEMPLATE.md`
- `ON_PAGE_OPTIMIZATION_TEMPLATE.md`
- `TECHNICAL_SEO_OBSERVATION_TEMPLATE.md`
- `INTERNAL_LINKING_PLAN_TEMPLATE.md`
- `CONTENT_REFRESH_TEMPLATE.md`
- `LOCAL_PAGE_EVALUATION_TEMPLATE.md`
- `SERP_SNIPPET_IMPROVEMENT_TEMPLATE.md`
- `SCHEMA_IMPLEMENTATION_HANDOFF_TEMPLATE.md`
- `PROGRAMMATIC_SEO_EVALUATION_TEMPLATE.md`
- `AEO_RECOMMENDATION_TEMPLATE.md`

### Template Lesson

A major lesson from Meredith’s build was:

**Do not rely on one giant shared template for multiple jobs.**

What emerged instead:

- smaller per-skill templates are better
- templates should only exist where fixed report shape is truly needed
- bloated mixed templates create drift

---

## 11. Meredith Skill Philosophy

The project established that built-in OpenClaw skills should not drive the architecture.

Meredith should rely mainly on:

- strong core files
- role files
- knowledge files
- a small, narrow custom skill footprint

The resulting design pattern became:

- core files = identity and behavior
- referenced files = role rules
- knowledge files = expertise
- skills = reusable execution routines

This is the model Meredith helped establish for future specialists.

---

## 12. First Meredith Custom Skills

The first three custom skills created for Meredith were:

- `seo-audit`
- `keyword-research`
- `content-cluster-planner`

### Naming Rule

A naming convention was explicitly settled:

- **folder names** use dash style
  - `seo-audit`
  - `keyword-research`
  - `content-cluster-planner`
- **skill names in `SKILL.md`** use underscore style
  - `seo_audit`
  - `keyword_research`
  - `content_cluster_planner`

This rule matters because earlier path and naming confusion had to be cleaned up.

---

## 13. SEO Audit Skill

### Original Problem

Meredith initially drifted during audit work into:

- JSON-LD generation
- FAQ drafting
- title/meta rewriting
- implementation packages
- option menus

That was wrong for the audit lane.

### What Was Tightened

To fix it, the following were repeatedly hardened:

- `skills/seo-audit/SKILL.md`
- `knowledge/templates/SEO_AUDIT_TEMPLATE.md`
- Meredith’s `SOUL.md`
- Meredith’s `AGENTS.md`

### Result

`seo_audit` became the benchmark Meredith skill.

Accepted behavior:

- concise
- structured
- audit-only
- no code by default
- no copy by default
- no schema generation by default
- no implementation artifacts by default
- suitable for Victor to review and route

### Why It Became the Benchmark

`seo_audit` became the benchmark because it had:

- one job only
- sharp role boundaries
- explicit “for / not for” logic
- a fixed output stop point
- forbidden default outputs
- clearly listed reference files
- a linear workflow
- a strong final rule preventing drift into execution

This pattern was treated as the model for future Meredith skills.

---

## 14. Keyword Research Skill

`keyword_research` was the main difficult skill in the documented Meredith build.

### Why It Was Difficult

Meredith kept leaking adjacent behavior into keyword work, including:

- AEO or FAQ targets
- implementation hints
- on-page notes
- title/meta ideas
- service and location variants
- long-tail sections
- strategist mode
- next-step offers
- memory contamination
- schema advice
- content structure bleed

### Core Diagnosis

The root issue was **scope contamination**.

`keyword_research` had become too broad and blended multiple jobs:

- primary keyword research
- supporting keywords
- semantic/entity opportunities
- local modifiers
- conversational intent
- AEO / FAQ discovery
- implementation thinking

### Major Conclusion

The correct fix was not endless patching.

Instead:

- narrow `keyword_research` into a pure page-target keyword research skill
- move conversational / AEO discovery into a separate future skill

That became one of the most important architecture decisions in the Meredith build.

### Conceptual Lane Split

The lane split that emerged:

- `seo_audit` = audit
- `keyword_research` = pure page-target keyword research
- `aeo_query_research` = conversational / AEO / FAQ / zero-click discovery
- `serp_intent_mapping` = page-role and intent split mapping
- `structured_data_review` = schema opportunities and risks review
- `content_cluster_planner` = cluster and internal linking planning

### Final Accepted Shape

Accepted keyword research structure centered around:

- `Objective`
- `Primary Keywords`
- `Secondary Keywords`
- `Semantic / Entity Terms`
- `Local Modifiers`
- `Recommended Page Target`
- `Risks / Notes`

It must not return:

- renamed drift sections
- long-tail sections by default
- FAQ sections
- implementation notes
- schema advice
- title/H1/H2 advice
- strategy notes
- next steps
- “If you want, I can…”

### Final Locked Posture

The locked posture established was:

- page-target keyword research only
- no AEO
- no FAQ discovery
- no consultant mode
- no implementation or schema advice
- no next-step offers
- no memory citations
- no prior-output formatting reuse
- no pricing / scheduling / promo modifiers unless explicitly requested
- no “near me” unless explicitly requested
- no symptom/problem queries unless explicitly requested
- no trust/proof terms unless explicitly requested
- no mixed residential/commercial unless explicitly requested

### Additional Lessons

Several other lessons came out of this:

- narrow skills beat bloated skills
- smaller models need stricter lane boundaries
- memory or prior sessions can contaminate output shape
- fresh sessions matter when a skill keeps reverting

At one point an even narrower version also worked well:

- `Objective`
- `Primary`
- `Supporting`

That reinforced the broader lesson that tighter scope usually produces better behavior.

---

## 15. Local Service Page Keyword Lesson

Another Meredith lesson was that local service pages do not always need the city appended to every keyword line.

A better approach can be:

- keep the page context local in the Objective
- let the content creator combine page location and keyword intent later when needed
- do not force a separate Local Modifiers section unless it is intentionally part of the skill or its output requirement

---

## 16. Possible Smaller Skill Split

Another architecture direction that surfaced was splitting keyword work into even smaller skills such as:

- `keyword_research`
  - Primary Keywords
  - Secondary Keywords
  - Tertiary Keywords
  - Short-Tail Keywords
  - Long-Tail Keywords
- `local_modifiers`
  - Local Modifiers
- `keyword_risks`
  - Risks / Notes

Why that idea mattered:

- smaller chunks
- lower token use
- easier debugging
- less drift
- better reliability
- less babysitting from Victor

Even though the main accepted posture remained a narrowed page-target `keyword_research`, this smaller-skill direction remained an important explored option.

---

## 17. Testing Conditions and Runtime Lessons

Meredith has primarily been tested through CLI, not normal chat.

Typical pattern:

`openclaw agent --agent seo --message "..."`

A repeated benchmark style was:

`openclaw agent --agent seo --message "/skill keyword_research Research keywords for an HVAC service page targeting air conditioning repair in Anaheim, California."`

The Anaheim HVAC use case became a recurring benchmark.

### Runtime Lessons

Strong lessons established:

- session reuse can preserve stale behavior
- fresh sessions matter when drift gets stubborn
- watcher/reload state affects whether a change is actually active

### Model Lesson

A key discovery during testing was that the seo agent was at one point still on `openai/gpt-5-mini` when Codex was thought to be active.

That showed:

- better models can improve output quality
- but architecture matters more
- strong models should not be expected to rescue weak skill design

### `/skill` Behavior Lesson

Another important truth established:

- explicit invocation format is `/skill <name> [input]`
- `/skill` behavior is still model-forwarded, not deterministic tool execution
- narrow skill scope reduces drift much more than adding more instructions

That is one of the main reasons Meredith’s skills had to stay so narrow.

---

## 18. Meredith Skill Stack Status

At the captured state in the documented history:

### Done / accepted

- `seo_audit`
- `keyword_research`

`seo_audit` was considered benchmark quality.

`keyword_research` was considered effectively solved and production-usable once narrowed properly.

### Existing early skills

- `seo-audit`
- `keyword-research`
- `content-cluster-planner`

### Next planned stack

- `aeo_query_research`
- `serp_intent_mapping`
- `structured_data_review`
- `content_cluster_planner` refinement

### Recommended next build order from the documented stage

1. `serp_intent_mapping`
2. `aeo_query_research`
3. `structured_data_review`
4. `content_cluster_planner` refinement

The reasoning was that `serp_intent_mapping` helps stop `aeo_query_research` from becoming another bloated keyword skill.

---

## 19. Definitions for the Next Meredith Skills

### `aeo_query_research`

#### Purpose

- conversational intent
- zero-click opportunities
- FAQ-style discovery
- answer-surface opportunities
- review / reputation answer visibility

#### Should do

- discover question-style queries
- discover symptom/problem phrasing
- discover comparison and decision phrasing
- discover review-platform / reputation queries
- identify answer visibility opportunities
- cluster queries by answer intent

#### Must not do

- choose the main page keyword target
- act like `keyword_research`
- generate titles/meta/H2s
- generate schema
- produce implementation steps
- produce full content briefs

### `serp_intent_mapping`

#### Purpose

- map a keyword set or page target to likely SERP intent mix
- help Victor decide whether one page is enough
- determine whether intent is mixed and needs a split
- route terms to the correct page type or skill lane

#### Should do

- classify intent mix:
  - service / commercial
  - urgent
  - informational
  - problem-diagnostic
  - local navigation
  - comparison
  - review / reputation
- identify whether one page can satisfy dominant intent
- identify intent split risk
- identify whether a keyword belongs on:
  - core service page
  - emergency page
  - subservice page
  - FAQ / AEO lane
  - review / reputation lane
- flag cannibalization risk between page types

#### Must not do

- generate keyword lists from scratch
- do AEO harvesting
- write page outlines
- write titles/meta/schema
- give implementation packages

#### Plain-English definition

`serp_intent_mapping` = **traffic cop between the other skills**

### `structured_data_review`

#### Purpose

- review schema opportunities
- review supported feature fit
- review quality / misuse risk
- align with Google structured data policies and Meredith’s structured data notes/templates

#### Should do

- identify relevant schema types supported by the page
- identify missing opportunities
- identify unsupported / misleading / risky markup ideas
- identify when markup does not match visible content
- identify when rich-result eligibility is plausible versus not plausible
- review risk against Google structured data policies

#### Must not do

- generate full JSON-LD by default
- act as an implementation skill
- promise rich results
- recommend schema unsupported by Google or unsupported by the page content

### `content_cluster_planner`

#### Purpose

- build cluster plans from Marvin’s framework
- map pillar pages
- map support pages
- map internal linking relationships
- show cluster gaps

#### Should do

- define pillar page
- define support pages
- map support page roles by intent/topic
- map internal linking relationships
- show cluster gaps
- keep page roles distinct

#### Must not do

- perform detailed keyword research inside the skill
- generate full copy
- generate implementation specs
- generate FAQ/AEO inventories unless explicitly provided

### Critical distinction that must stay clean

This distinction was explicitly established and must stay clean:

- `aeo_query_research` asks: **What are people asking?**
- `serp_intent_mapping` asks: **What kind of page should satisfy this intent?**

That line must not blur.

---

## 20. Best Plain-English Summary of Meredith

Meredith is a hardened OpenClaw SEO and Search Visibility Specialist built to produce disciplined, narrow, reviewable outputs for Victor.

She was deliberately shaped to:

- stay in role
- avoid implementation drift
- avoid broad strategist drift
- avoid copywriter/dev behavior
- operate through layered architecture
- rely on narrow custom skills instead of bloated prompts

The biggest lessons Meredith taught the system were:

- narrow skills beat bloated skills
- strong defaults beat constant corrective prompting
- knowledge belongs in knowledge files, not core files
- runtime/session behavior matters during testing
- architecture matters more than trying to rescue weak design with a stronger model

In short:

**Meredith is the search-visibility specialist layer under Victor, built to audit, analyze, prioritize, recommend, and stop.**