writeonce/docs/future-scope/ai-agents-content-management.md

AI Agents and Content Management

Context

AI agents (Claude Code, Copilot, Cursor, custom agents) work within a specific project or working directory. Their sessions, context, and understanding are scoped to that directory. This works well when projects are completely different domains.

But writeonce content is not isolated — articles reference each other, share tags, build on concepts from other articles. An agent editing gitlab-runner-with-kubernetes-executor.md would benefit from knowing that auto-scale-gitlab-runner-using-aws-spot-instance.md exists and covers related infrastructure. Without explicit mappings, the agent treats each article as an island.

Problem

1. Agents lack cross-article awareness. When asked to write or update an article about Kubernetes, the agent doesn't know that related articles about Docker, CI/CD, or AWS already exist in the content directory — unless it manually searches.

2. No semantic grouping. Tags provide flat categorization (kubernetes, ci-cd), but they don't express relationships: "this article is a prerequisite for that one", "these three articles form a series", "this article supersedes that one."

3. Context window waste. Without mappings, the agent must scan all articles to find related content. With explicit mappings, it can load exactly the relevant files.

Solution: Metadata-Driven Content Mappings

Users define relationships between articles in the JSON metadata. These mappings serve two purposes:

1. Human navigation — rendered as "related articles" links on the site
2. Agent context — when an agent works on an article, it loads the mapped articles into its context for cross-referencing

Mapping Fields in JSON Metadata

Per 06-markdown-render.md, the JSON metadata is minimal. Add a mappings field:

{
  "sys_title": "gitlab-runner-with-kubernetes-executor",
  "title": "Gitlab Runner with Kubernetes Executor",
  "published": true,
  "author": "Shoney Arickathil",
  "tags": ["kubernetes", "gitlab", "ci-cd"],
  "published_on": 1740950884,
  "mappings": {
    "related": ["auto-scale-gitlab-runner-using-aws-spot-instance"],
    "prerequisite": ["linux-misc"],
    "series": {
      "name": "gitlab-runner",
      "order": 2
    }
  }
}

Mapping Types

Type	Meaning	Agent Use
related	Topically related articles	Agent loads these for cross-reference when editing
prerequisite	Articles the reader should read first	Agent ensures no concept duplication, references prerequisites instead of re-explaining
series	Articles that form an ordered sequence	Agent maintains narrative continuity across the series
supersedes	This article replaces an older one	Agent can mark the old article as outdated or unpublished
references	External articles or URLs the content builds on	Agent checks links are still valid, cites them properly

Directory Structure with Mappings

content/
  gitlab-runner-with-kubernetes-executor/
    gitlab-runner-with-kubernetes-executor.json    # metadata + mappings
    gitlab-runner-with-kubernetes-executor.md      # full article
  auto-scale-gitlab-runner-using-aws-spot-instance/
    auto-scale-gitlab-runner-using-aws-spot-instance.json
    auto-scale-gitlab-runner-using-aws-spot-instance.md
  linux-misc/
    linux-misc.json
    linux-misc.md

Agent Workflows

1. Writing a New Article

The author asks an agent: "Write an article about deploying GitLab Runner on ECS."

The agent:

1. Scans the content directory for existing articles with tags gitlab, ci-cd, aws
2. Finds gitlab-runner-with-kubernetes-executor and auto-scale-gitlab-runner-using-aws-spot-instance
3. Reads their .md files to understand what's already covered
4. Writes the new article, referencing existing articles rather than re-explaining shared concepts
5. Suggests mappings.related entries for the new article's JSON

2. Updating an Existing Article

The author asks: "Update the Kubernetes executor article with the new runner token format."

The agent:

1. Reads the article's JSON metadata and .md content
2. Reads the mappings.related articles to check for consistency
3. Makes the update in the .md file
4. Checks if the change affects any prerequisite or series articles
5. inotify detects the .md change → store rebuilds → subscribers notified

3. Content Audit

The author asks: "Which articles reference outdated AWS configurations?"

The agent:

1. Loads all article metadata (the Store already indexes everything)
2. Follows mappings to build a dependency graph
3. Reads the .md files of articles tagged with aws
4. Identifies outdated patterns (old SDK versions, deprecated services)
5. Reports findings with links to specific articles and line numbers

4. Series Management

The author asks: "Add a new part to the gitlab-runner series."

The agent:

1. Finds all articles with mappings.series.name == "gitlab-runner"
2. Reads them in order to understand the narrative arc
3. Writes the new article continuing from where the series left off
4. Sets mappings.series.order to the next number
5. Updates the previous article's mappings to reference the new one

Integration with writeonce Architecture

Store Index

Add a mappings index alongside the existing title, date, and tag indexes:

data/
  articles.seg
  index/
    title.idx
    date.idx
    tags.idx
    mappings.idx    # sys_title → related sys_titles

The mappings index allows efficient traversal: "give me all articles related to X" without scanning every article's JSON.

Template Rendering

The article.htmlx template can render related articles:

<article>
  <h1>{{article.title}}</h1>
  {{article.content_html}}

  {{#each article.related}}
  <aside class="related">
    <h3>Related</h3>
    <ul>
      <li><a href="/blog/{{sys_title}}">{{title}}</a></li>
    </ul>
  </aside>
  {{/each}}
</article>

Subscription

When a mapped article changes, subscribers to related articles can optionally be notified. If article A lists article B in mappings.related, and article B is updated, subscribers to article A can receive a notification that related content changed.

Agent Configuration

For agents to use the mappings effectively, the project can include an agent instruction file (e.g., CLAUDE.md or .agent/instructions.md):

## Content Management

- Articles are in `content/{sys_title}/{sys_title}.md`
- Metadata is in `content/{sys_title}/{sys_title}.json`
- Before writing or editing an article, read its `mappings` field and load related articles for context
- When creating a new article, suggest appropriate `mappings` based on tags and content overlap
- Maintain narrative continuity within `series` mappings
- Do not duplicate explanations that exist in `prerequisite` articles — reference them instead

This turns the content directory into an agent-navigable knowledge graph where the metadata provides the edges and the markdown files provide the nodes.