Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

seo(blog): revise ai-agent-team and add dateModified (#397)

LindsayLiu77770deb694240e
diff --git a/src/web/public/blog/ai-agent-team/handoff-contract.webp b/src/web/public/blog/ai-agent-team/handoff-contract.webp
new file mode 100644
index 000000000..b67de12f2
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/handoff-contract.webp differ
diff --git a/src/web/public/blog/ai-agent-team/hero.png b/src/web/public/blog/ai-agent-team/hero.png
deleted file mode 100644
index dcfa111e2..000000000
Binary files a/src/web/public/blog/ai-agent-team/hero.png and /dev/null differ
diff --git a/src/web/public/blog/ai-agent-team/hero.webp b/src/web/public/blog/ai-agent-team/hero.webp
index c97214a14..e71a7c770 100644
Binary files a/src/web/public/blog/ai-agent-team/hero.webp and b/src/web/public/blog/ai-agent-team/hero.webp differ
diff --git a/src/web/public/blog/ai-agent-team/roles-structure.webp b/src/web/public/blog/ai-agent-team/roles-structure.webp
new file mode 100644
index 000000000..dc0c68040
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/roles-structure.webp differ
diff --git a/src/web/public/blog/ai-agent-team/team-structure.png b/src/web/public/blog/ai-agent-team/team-structure.png
deleted file mode 100644
index a304603dd..000000000
Binary files a/src/web/public/blog/ai-agent-team/team-structure.png and /dev/null differ
diff --git a/src/web/public/blog/ai-agent-team/team-vs-single.webp b/src/web/public/blog/ai-agent-team/team-vs-single.webp
new file mode 100644
index 000000000..562088f01
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/team-vs-single.webp differ
diff --git a/src/web/public/blog/ai-agent-team/walkthrough-brief-handoff.webp b/src/web/public/blog/ai-agent-team/walkthrough-brief-handoff.webp
new file mode 100644
index 000000000..fd782bd02
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/walkthrough-brief-handoff.webp differ
diff --git a/src/web/public/blog/ai-agent-team/walkthrough-calendar.webp b/src/web/public/blog/ai-agent-team/walkthrough-calendar.webp
new file mode 100644
index 000000000..0dc756878
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/walkthrough-calendar.webp differ
diff --git a/src/web/public/blog/ai-agent-team/walkthrough-org-chart.webp b/src/web/public/blog/ai-agent-team/walkthrough-org-chart.webp
new file mode 100644
index 000000000..c523c6dc6
Binary files /dev/null and b/src/web/public/blog/ai-agent-team/walkthrough-org-chart.webp differ
diff --git a/src/web/public/blog/ai-agent-team/workflow.png b/src/web/public/blog/ai-agent-team/workflow.png
deleted file mode 100644
index b77de9c07..000000000
Binary files a/src/web/public/blog/ai-agent-team/workflow.png and /dev/null differ
diff --git a/src/web/src/app/blog/[slug]/page.tsx b/src/web/src/app/blog/[slug]/page.tsx
index 73e2cda8f..27a59ea13 100644
--- a/src/web/src/app/blog/[slug]/page.tsx
+++ b/src/web/src/app/blog/[slug]/page.tsx
@@ -3,6 +3,7 @@ import { notFound } from "next/navigation";
import Link from "next/link";
import { ArrowLeft, ArrowRight } from "lucide-react";
import { getAllPosts, getPostBySlug } from "@/lib/blog/posts";
+import { buildBlogPostingJsonLd } from "@/lib/blog/json-ld";
export const dynamicParams = false;
@@ -32,6 +33,7 @@ export async function generateMetadata({
url: `https://alook.ai/blog/${post.slug}`,
type: "article",
publishedTime: post.date,
+ ...(post.dateModified ? { modifiedTime: post.dateModified } : {}),
authors: [post.author],
images: [
{
@@ -68,24 +70,7 @@ export default async function BlogPostPage({
`@/content/${slug}.mdx`
);
- const blogPostingJsonLd = {
- "@context": "https://schema.org",
- "@type": "BlogPosting",
- headline: post.title,
- description: post.excerpt,
- datePublished: post.date,
- author: {
- "@type": "Person",
- name: post.author,
- },
- publisher: {
- "@type": "Organization",
- name: "Alook AI",
- url: "https://alook.ai",
- },
- url: `https://alook.ai/blog/${post.slug}`,
- ...(post.image && { image: `https://alook.ai${post.image}` }),
- };
+ const blogPostingJsonLd = buildBlogPostingJsonLd(post);
return (
<>
@@ -114,7 +99,7 @@ export default async function BlogPostPage({
<h1 className="font-news text-4xl sm:text-5xl font-semibold tracking-tight leading-[1.12]">
{post.title}
</h1>
- <div className="mt-6 flex items-center gap-3 text-sm text-muted-foreground">
+ <div className="mt-6 flex flex-wrap items-center gap-x-3 gap-y-1 text-sm text-muted-foreground">
<span className="font-medium text-foreground/70">{post.author}</span>
<span className="text-muted-foreground/40">/</span>
<span>
@@ -124,6 +109,19 @@ export default async function BlogPostPage({
day: "numeric",
})}
</span>
+ {post.dateModified && post.dateModified !== post.date ? (
+ <>
+ <span className="text-muted-foreground/40">/</span>
+ <span>
+ Updated{" "}
+ {new Date(post.dateModified).toLocaleDateString("en-US", {
+ year: "numeric",
+ month: "long",
+ day: "numeric",
+ })}
+ </span>
+ </>
+ ) : null}
<span className="text-muted-foreground/40">/</span>
<span>{post.readingTime}</span>
</div>
diff --git a/src/web/src/content/ai-agent-team.mdx b/src/web/src/content/ai-agent-team.mdx
index 75d13f9dd..2c1dadaca 100644
--- a/src/web/src/content/ai-agent-team.mdx
+++ b/src/web/src/content/ai-agent-team.mdx
@@ -2,9 +2,10 @@ export const metadata = {
slug: "ai-agent-team",
title: "How to Build an AI Agent Team: Roles, Handoffs, and Oversight",
date: "2026-06-08",
+ dateModified: "2026-07-23",
author: "Alook Team",
excerpt:
- "Build an AI agent team around one reliable workflow with defined roles, structured handoffs, shared context, failure paths, and human approval.",
+ "Build an AI agent team around one reliable workflow with defined roles, structured handoffs, recorded decisions, failure paths, and human approval.",
readingTime: "7 min read",
image: "/blog/ai-agent-team/hero.webp",
};
@@ -58,79 +59,77 @@ export const jsonLd = [
},
];
-![Conceptual AI agent team workflow with coordination, analysis, execution, and a completed output](/blog/ai-agent-team/hero.webp)
+![AI agent team workflow: Owner, Orchestrator, Specialists, handoff artifact, Reviewer, and human approval](/blog/ai-agent-team/hero.webp)
-*A conceptual workflow showing defined roles and handoffs, not a product screenshot.*
+*Clear roles, structured handoffs, and human oversight — a conceptual workflow, not a product screenshot.*
-An AI agent team is a group of agents with defined roles working on one shared workflow. One agent might investigate an issue, another might implement a change, and a review step checks the result before it moves forward. The value comes from clear ownership and reliable handoffs, not from adding as many agents as possible.
+An AI agent team is a group of agents with defined roles working on one shared workflow. One agent might investigate an issue. Another prepares a change. A review step checks the result before anything moves forward.
-You still set the goal, control access, and approve important decisions. The agents handle scoped work inside those boundaries.
+Clear ownership and reliable handoffs matter more than stacking agents.
+
+You still set the goal, control access, and approve the decisions that can hurt customers or production. The agents handle scoped work inside those boundaries. If those boundaries stay fuzzy, more agents only multiply the mess.
## What is an AI agent team?
-A single AI agent receives instructions and produces a result. An AI agent team divides a larger workflow into stages, then assigns each stage to a role with the right tools and context.
+A single AI agent receives instructions and produces a result. An AI agent team divides a larger workflow into stages, then assigns each stage to a role with the right tools and context. The difference shows up when one stage needs a permission another stage should never hold.
-For example, a software workflow might include:
+Take a bug that needs a draft pull request. One useful shape looks like this:
-- An investigator that reproduces a bug and identifies likely causes
+- An investigator that reproduces the bug and names likely causes
- A developer that prepares a code change
- A reviewer that checks the diff, tests, and acceptance criteria
- A human who decides whether the change is ready to merge
-These are workflow roles, not job titles. The same agent can own more than one role when the work is simple. Separate agents become useful when stages need different permissions, instructions, or review standards.
+These are workflow roles, not job titles. The same agent can own more than one role when the work is simple. Separate agents help when stages need different permissions, instructions, or review standards.
+
+Want a harder test? Ask whether two stages would still make sense if each one used a different tool set.
## AI agent team vs single agent
Multiple agents introduce coordination overhead. Use a team only when that overhead solves a real problem.
-A single agent is usually enough when:
+A single agent is usually enough when the task has one clear output, the same context and tools apply from start to finish, a failure does not need a separate recovery path, and one review point at the end is enough.
-- The task has one clear output.
-- The same context and tools apply from start to finish.
-- A failure does not require a separate recovery path.
-- One review point at the end is sufficient.
+When does a team earn the extra coordination cost? When stages have different responsibilities. When one stage should not hold another stage's tools. When a specialist needs to challenge another agent's output, work must continue through repeatable handoffs, or you need to trace which role made each decision.
-An AI agent team becomes useful when:
+Vendor docs draw a related line inside one product. Anthropic's [Claude Code agent teams](https://code.claude.com/docs/en/agent-teams) treat teammates as coordinated sessions with a shared task list and messaging, and they warn that the mode is experimental and token-heavy. That is still one runtime coordinating peers. The design questions in this guide sit one layer up: who owns each stage, what artifact moves between stages, and where a person must approve. If your problem is really "two Claude sessions need a mailbox," start with that product doc. If your problem is "two different coding agents need a durable handoff across tools," keep reading.
-- The workflow has distinct stages with different responsibilities.
-- One stage should not have access to another stage's tools.
-- A specialist needs to review or challenge another agent's output.
-- Work must continue through repeatable handoffs.
-- You need to trace which role made each decision.
+Start with one agent. Split the workflow only after you can name the handoff the next agent will own.
-Start with one agent. Split the workflow only after you can name the handoff that the next agent will own.
+![When to use a single agent versus an AI agent team](/blog/ai-agent-team/team-vs-single.webp)
+
+*Start with one agent. Move to a team only when stages, permissions, or review need a real handoff.*
## The roles inside an AI agent team
-There is no fixed list of agents that every team needs. A useful team is designed around a workflow, but most setups contain some version of these responsibilities.
+There is no fixed roster every team must hire. Design around a workflow, then map responsibilities.
-**The owner sets the outcome.** This is usually a person. The owner defines success, grants access, and decides which actions require approval.
+The **owner** is usually a person who defines success, grants access, and decides which actions need approval. The **orchestrator** assigns a stage, records status, passes outputs onward, and surfaces failures so the coordination layer never hides what happened. **Specialists** do scoped work such as research, code changes, and analysis, with instructions and permissions matched to the task they own.
-**The orchestrator keeps work moving.** It assigns a stage, records status, passes outputs to the next role, and makes failures visible. The orchestration layer should not hide what happened.
+A **reviewer** can be another agent for routine checks. High-impact decisions still belong to a person.
-**Specialists perform scoped work.** A researcher gathers evidence. A developer changes code. An analyst evaluates data. Their instructions and permissions should match the task they own.
+One agent may cover several of those jobs at first. Split them when different tools, context, or approval rules make separation safer or easier to evaluate. If you cannot say which role owns a failure, the roster is still too vague.
-**A reviewer checks the result.** Review can be handled by another agent for routine checks, but high-impact decisions still belong to a person.
+![Roles inside an AI agent team: Owner, Orchestrator, Specialists, and Reviewer](/blog/ai-agent-team/roles-structure.webp)
-One agent may cover several responsibilities at first. Split them when different tools, context, or approval rules make separation safer or easier to evaluate.
+*Owner sets the outcome. Orchestrator keeps work moving. Specialists do scoped work. Reviewer checks the result.*
## How AI agents coordinate and hand off work
-A handoff needs more than a message saying “continue.” The next agent needs a clear contract.
-
-**Scope.** State what the current agent owns and what it must leave untouched.
+A handoff needs more than a message that says “continue.” The next agent needs a contract.
-**Input.** Identify the source material, previous decisions, and constraints that the agent should use.
+- **Scope** — what the current agent owns, and what it must leave alone
+- **Input** — source material, earlier decisions, and constraints the agent should use
+- **Output** — the artifact the next step expects: research brief, issue analysis, patch, test report, or approval request
+- **Completion criteria** — how the team knows the stage is finished; if a check can be written down, write it down
+- **Failure path** — what happens when information is missing, a tool fails, or review rejects the result (silent retries are not always right)
+- **Approval boundary** — which actions may proceed automatically, and which must wait for a person
-**Output.** Define the artifact the next step expects, such as a research brief, issue analysis, patch, test report, or approval request.
+Recorded decisions help the next role, but only when that role knows how to apply them. Contracts still come first.
-**Completion criteria.** Explain how the team knows the stage is finished. If a check can be made explicit, write it down.
+![Handoff contract: Scope, Input, Output, Completion criteria, Failure path, Approval boundary](/blog/ai-agent-team/handoff-contract.webp)
-**Failure path.** Decide what happens when information is missing, a tool fails, or the result does not pass review. Retrying silently is not always the right response.
-
-**Approval boundary.** Specify which actions can proceed automatically and which must wait for a person.
-
-Shared context helps agents understand earlier decisions, but it does not replace these contracts. A recorded decision is useful only when the next role knows how to apply it.
+*A handoff needs a contract — not a message that only says “continue.”*
For a deeper explanation of this coordination layer, read the guide to [AI orchestration](/blog/ai-agent-orchestration).
@@ -138,48 +137,37 @@ For a deeper explanation of this coordination layer, read the guide to [AI orche
### 1. Choose one repeatable workflow
-Pick work with a visible trigger, a defined output, and a result you can inspect. A bug report moving toward a draft pull request is easier to evaluate than a broad instruction such as “improve the product.”
+Pick work with a visible trigger, a defined output, and a result you can inspect. A bug report moving toward a draft pull request is easier to evaluate than “improve the product.”
### 2. Map the stages before choosing agents
-Write the workflow as a sequence. For a bug:
-
-1. Reproduce the problem.
-2. Identify the likely cause.
-3. Prepare a change.
-4. Run the required checks.
-5. Review the diff and evidence.
-6. Ask a person to approve the next action.
-
-The stages reveal which roles you need. They also show where a handoff may fail.
+Write the workflow as a sequence. For a bug: reproduce the problem, identify the likely cause, prepare a change, run the required checks, review the diff and evidence, then ask a person to approve the next action. Those stages reveal which roles you need and where a handoff may fail.
### 3. Give each role limited access
-An investigator may only need the repository, issue details, and logs. A developer may need permission to edit a branch and run tests. Neither role needs permission to merge into production.
-
-Limit access by default. Expand it only when a tested workflow requires more.
+An investigator may only need the repository, issue details, and logs. A developer may need permission to edit a branch and run tests. Neither role needs permission to merge into production. Limit access by default; expand it only when a tested workflow requires more.
### 4. Define handoff artifacts
-Do not rely on a long chat transcript as the only record. Ask each role to leave a structured result: findings, changed files, test output, unresolved questions, and the recommended next step.
-
-This gives the next agent a stable starting point and makes human review faster.
+Do not rely on a long chat transcript as the only record. Ask each role to leave a structured result: findings, changed files, test output, unresolved questions, and the recommended next step. That gives the next agent a stable starting point and makes human review faster.
### 5. Test normal cases and failures
-Run the workflow with representative inputs. Then test missing information, conflicting instructions, tool errors, failed checks, and outputs that should be rejected.
-
-A successful run tells you the path can work. A failed run shows whether the team can stop safely and explain what happened.
+Run the workflow with representative inputs first. Then break it on purpose: missing information, conflicting instructions, tool errors, failed checks, and outputs that should be rejected. A successful run only shows the path can work; a failed run shows whether the team can stop safely and explain what happened.
### 6. Add scheduling after the workflow is reliable
-Recurring work should be scheduled only after the unscheduled version produces useful, reviewable results. Keep a history of instructions, decisions, and outputs so you can investigate changes in behavior.
+Recurring work belongs on a calendar only after the unscheduled version produces useful, reviewable results. Keep a history of instructions, decisions, and outputs so you can investigate changes in behavior when the Tuesday run looks nothing like Monday's.
You can find additional structures in the guide to [multi-agent workflow patterns](/blog/multi-agent-workflow-patterns).
## Building an AI agent team with Alook
-[Alook](https://alook.ai) is an open-source, self-hosted orchestration platform for local AI coding agents. It currently supports Claude Code, Codex, and OpenCode.
+[Alook](https://alook.ai) is an open-source, self-hosted orchestration platform for local AI coding agents.
+
+### Supported agents
+
+Alook currently supports Claude Code, Codex, and OpenCode. Cursor, Hermes, and OpenClaw are listed as coming soon.
Alook gives agents an operating structure:
@@ -191,48 +179,67 @@ Alook gives agents an operating structure:
- **Traceability** records instructions, decisions, and replies.
- **Local execution** keeps your agents and their tool access on your machine.
-Alook provides the coordination layer. The underlying agent still needs appropriate instructions, tools, and model access. Human approval remains part of any workflow where the outcome can affect customers, money, legal obligations, or production systems.
+### An example walkthrough: four roles, one brief
-If you are deciding whether a task needs an agent at all, start with the explanation of an [AI agent vs chatbot](/blog/ai-agent-vs-chatbot).
+The structure above becomes clearer with a concrete team. On July 3, 2026, [Akshay Pachaar published a public walkthrough](https://x.com/akshay_pachaar/status/2073050056299835736) that sets up a four-agent org chart for one competitive-intelligence job: track a pricing page, schedule the check, and notify a person when something changes.
-## Common AI agent team failure modes
+The roles in that walkthrough:
-**Roles are too broad.** “Own engineering” gives an agent no useful boundary. “Investigate this issue and return reproduction steps plus likely files” can be evaluated.
+- **Atlas (CEO)** is the human’s single point of contact. It receives the brief and delegates.
+- **Mara (PM)** turns the brief into a spec and routes work. Specialists talk to Mara, not to each other or to Atlas directly.
+- **Theo (engineer)** builds and maintains the tracker for the watched page.
+- **Ren (ops)** watches the output and emails the human when a tracked change appears.
-**The team starts too large.** Every additional agent adds another handoff, permission boundary, and failure point. Add roles in response to a tested need.
+![Four-agent org chart: Atlas (CEO), Mara (PM), Theo (Engineer), Ren (Ops)](/blog/ai-agent-team/walkthrough-org-chart.webp)
-**Outputs are not structured.** If the next step has to infer what happened from a long transcript, the handoff is fragile.
+*Org chart from the walkthrough: reporting lines Atlas → Mara → Theo and Ren. Source: [Akshay Pachaar on X](https://x.com/akshay_pachaar/status/2073050056299835736).*
-**Agents can act beyond their role.** Broad permissions turn a small mistake into a larger incident. Separate preparation from approval for high-impact actions.
+Setup starts with `npx @alook/app onboard`, which connects a local daemon and opens a dashboard. From there you create each agent, claim its `@alook.ai` inbox, and wire the reporting lines: Atlas → Mara → Theo and Ren.
-**Failures are hidden.** A retry loop is not a recovery strategy. The workflow should record the error, preserve completed work, and escalate when it cannot continue safely.
+Once the chart is live, the human talks to Atlas with one scoped brief. Atlas emails Mara. Mara sends Theo a structured spec covering what to build, what to snapshot, how often to run, and what a readable report looks like. Theo acknowledges over email, implements the tracker with the tools available on the machine, and reports back. That chain is the handoff contract in practice: brief → spec → implementation note, each owned by a different role.
-**Human review is added too late.** Approval points should be designed with the workflow, not attached after the agents are already acting.
+![Chat with Atlas showing a brief emailed to Mara and a structured plan handed to Theo](/blog/ai-agent-team/walkthrough-brief-handoff.webp)
-## AI agent team FAQ
+*One brief to Atlas becomes an email handoff to Mara, then a scoped plan for Theo. Source: [Akshay Pachaar on X](https://x.com/akshay_pachaar/status/2073050056299835736).*
-**What is an AI agent team?**
+After the unattended path looks reliable, the recurring check lands on the calendar. Ren owns the alert when the watched value actually moves.
-It is a group of agents with defined roles that work on one shared workflow. Each role owns a stage and passes a structured result to the next step.
+![Calendar with a daily recurring price-tracker task for the agent team](/blog/ai-agent-team/walkthrough-calendar.webp)
-**When should you use multiple AI agents instead of one?**
+*Scheduling comes after the workflow works once: a daily run to catch the next change. Source: [Akshay Pachaar on X](https://x.com/akshay_pachaar/status/2073050056299835736).*
-Use multiple agents when stages need different instructions, tools, permissions, context, or review. Keep one agent when the task is short and self-contained.
+That loop matches the earlier design rules: limited access by role, email threads as handoff artifacts, scheduling after the workflow works once, and a person still sitting at the approval boundary for anything that should not fire silently.
+
+Alook provides the coordination layer. The underlying agent still needs appropriate instructions, tools, and model access. Human approval remains part of any workflow where the outcome can affect customers, money, legal obligations, or production systems.
-**How many agents should a team have?**
+If you are deciding whether a task needs an agent at all, start with the explanation of an [AI agent vs chatbot](/blog/ai-agent-vs-chatbot).
-There is no universal number. Start with the fewest roles needed for one reliable workflow, then add an agent only when a real handoff requires it.
+## Common AI agent team failure modes
-**Which AI agents does Alook support?**
+**Roles are too broad** when the brief sounds like “own engineering.” A request such as “investigate this issue and return reproduction steps plus likely files” can actually be evaluated. **Teams also start too large** when every new agent adds another handoff, permission boundary, and failure point before a tested need exists.
-Alook currently supports Claude Code, Codex, and OpenCode. Cursor, Hermes, and OpenClaw are listed as coming soon.
+**Unstructured outputs** force the next step to infer what happened from a long transcript, and the handoff gets fragile. **Over-broad permissions** turn a small mistake into a larger incident, so separate preparation from approval for high-impact actions.
-**Does an AI agent team need human oversight?**
+**Hidden failures** are easy to miss when a retry loop pretends to be recovery. The workflow should record the error, preserve completed work, and escalate when it cannot continue safely. **Late human review** is the other trap: approval points belong in the design, not as an afterthought once agents are already acting.
-Yes. People should approve customer commitments, financial actions, legal decisions, pricing changes, and high-risk production work.
+That list is incomplete on purpose.
+
+## AI agent team FAQ
+
+**What is an AI agent team?** It is a group of agents with defined roles that work on one shared workflow. Each role owns a stage and passes a structured result to the next step.
+
+**When should you use multiple AI agents instead of one?** Use multiple agents when stages need different instructions, tools, permissions, context, or review. Keep one agent when the task is short and self-contained — especially when a handoff would only add delay.
+
+**How many agents should a team have?** Start with the fewest roles needed for one reliable workflow, then add an agent only when a real handoff requires it.
+
+**Which AI agents does Alook support?** Claude Code, Codex, and OpenCode are available today. Cursor, Hermes, and OpenClaw are listed as coming soon.
+
+**Does an AI agent team need human oversight?** Yes. People should approve customer commitments, financial actions, legal decisions, pricing changes, and high-risk production work. Design those gates before the agents start acting.
## Start with one handoff
-Choose a workflow you already understand. Define two stages, write down the artifact that moves between them, and decide where a person must approve the result.
+Name the artifact first.
+
+Choose a workflow you already understand. Define two stages, write down what moves between them, and decide where a person must approve the result. If you cannot name that artifact yet, stay on a single agent.
To set up Alook for your local coding agents, run `npx @alook/app onboard`. You can also review the project on [GitHub](https://github.com/alookai/alook) or browse the current [Alook templates](https://alook.ai/templates).
diff --git a/src/web/src/lib/blog/json-ld.test.ts b/src/web/src/lib/blog/json-ld.test.ts
new file mode 100644
index 000000000..34ca23929
--- /dev/null
+++ b/src/web/src/lib/blog/json-ld.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import type { BlogPost } from "./types";
+import { buildBlogPostingJsonLd } from "./json-ld";
+
+const base: BlogPost = {
+ slug: "sample",
+ title: "Sample",
+ date: "2026-06-08",
+ author: "Alook Team",
+ excerpt: "Excerpt",
+ readingTime: "5 min read",
+ image: "/blog/sample/hero.webp",
+};
+
+describe("buildBlogPostingJsonLd", () => {
+ it("omits dateModified when not set", () => {
+ const jsonLd = buildBlogPostingJsonLd(base);
+ expect(jsonLd.datePublished).toBe("2026-06-08");
+ expect(jsonLd).not.toHaveProperty("dateModified");
+ expect(jsonLd.image).toBe("https://alook.ai/blog/sample/hero.webp");
+ });
+
+ it("includes dateModified when set", () => {
+ const jsonLd = buildBlogPostingJsonLd({
+ ...base,
+ dateModified: "2026-07-23",
+ });
+ expect(jsonLd.datePublished).toBe("2026-06-08");
+ expect(jsonLd.dateModified).toBe("2026-07-23");
+ });
+});
diff --git a/src/web/src/lib/blog/json-ld.ts b/src/web/src/lib/blog/json-ld.ts
new file mode 100644
index 000000000..1e09a1290
--- /dev/null
+++ b/src/web/src/lib/blog/json-ld.ts
@@ -0,0 +1,23 @@
+import type { BlogPost } from "./types";
+
+export function buildBlogPostingJsonLd(post: BlogPost) {
+ return {
+ "@context": "https://schema.org",
+ "@type": "BlogPosting",
+ headline: post.title,
+ description: post.excerpt,
+ datePublished: post.date,
+ ...(post.dateModified ? { dateModified: post.dateModified } : {}),
+ author: {
+ "@type": "Person",
+ name: post.author,
+ },
+ publisher: {
+ "@type": "Organization",
+ name: "Alook AI",
+ url: "https://alook.ai",
+ },
+ url: `https://alook.ai/blog/${post.slug}`,
+ ...(post.image ? { image: `https://alook.ai${post.image}` } : {}),
+ };
+}
diff --git a/src/web/src/lib/blog/types.ts b/src/web/src/lib/blog/types.ts
index 0cb719269..5183257d1 100644
--- a/src/web/src/lib/blog/types.ts
+++ b/src/web/src/lib/blog/types.ts
@@ -2,6 +2,8 @@ export type BlogPost = {
slug: string;
title: string;
date: string;
+ /** ISO date (YYYY-MM-DD) when the published post was last revised. */
+ dateModified?: string;
author: string;
excerpt: string;
readingTime: string;