How We Built Reviewable AI Content Generation with Inline Comments and Brand-Aware Images
AI content generation is usually demonstrated as a blank box and a finished draft. That is the least interesting part of the workflow.
The real work starts after the draft exists. An editor highlights one sentence and asks for evidence. A product marketer wants a paragraph to use the language customers use. A brand lead wants the hero image to follow the visual system without becoming a generic logo stamp. Three reviewers make changes at different times, and none of them expects the tool to rewrite sections they already approved.
We built inline comments and brand-aware image generation in Seerly for that part of the process. The feature is not a chat box attached to an editor. It is a set of contracts that keeps a human selection anchored as the article changes, confines an AI revision to the requested region, turns every proposed edit into a reviewable diff, and carries brand guidelines into both the article and the image pipeline.
This article explains the key engineering choices. I will leave out low-level implementation detail that does not improve the story, but I will be specific about the invariants that make the workflow trustworthy.
1. The problem is not generation. It is controlled change
A one-shot AI writing tool optimizes for an impressive first response. An editorial system has a different job: it must survive many small, partially dependent decisions.
Suppose a reviewer comments, “Use a concrete example here,” on the second paragraph of a section. While that comment is open, another editor tightens the introduction. Character offsets move. Paragraph indexes may move. The selected sentence might be reworded slightly. When the first reviewer returns, the system still needs to identify the intended passage.
Then comes a second problem. The model needs enough context to make the change coherent, but it must not take that context as permission to revise the whole article. A narrow request should produce a narrow diff.
Finally, the new copy still has to match the article's search intent, brand voice, target audience, and terminology. If each revision is treated as an isolated prompt, brand consistency declines with every round of editing.
We framed the feature around three invariants:
- The human chooses where a change belongs. The model never invents the insertion point.
- The model can only rewrite a bounded region. Context informs the edit but does not expand its authority.
- Every change is proposed before it becomes a version. Reviewers can inspect, accept, or reject the actual diff.
Those invariants connect content collaboration, AI revision, and version history into one system.
2. An inline comment needs more than a character offset
The obvious way to store an inline comment is a start and end position. It works until the document changes, which is precisely when a comment system becomes valuable.
Our comment anchor stores the reviewer's selected text, a short prefix and suffix around it, the block where it was last seen, and whether it is a span or a point. A span means “change this passage.” A point means “insert something here” without a text selection.
The block index is a hint, not the source of truth. When the server resolves comments, it searches for the quoted passage and uses the surrounding text to disambiguate repeated phrases. If the passage moved, the prefix and suffix can move with it. If it was edited lightly, a guarded fuzzy match can recover a sufficiently distinctive selection.
Short selections are handled more conservatively. A few characters can approximately match almost anywhere, so guessing would risk changing the wrong sentence. When the anchor cannot be resolved with confidence, the comment becomes orphaned and stays visible as unresolved.
That failure mode is intentional. Silently dropping feedback is indistinguishable from ignoring the reviewer, and attaching it to the wrong passage is worse.
Comments also carry their own lifecycle. Open comments travel forward when a new article version is saved. Resolved comments remain as history with the version that resolved them. This makes the comment record part of the editorial audit trail rather than temporary UI state.
3. We convert selections into bounded editing windows
The reviewer selects a phrase, but replacing only that phrase is often too restrictive. “Add a supporting example” may require a new paragraph. “Make this argument clearer” may require restructuring the current paragraph. Deleting a redundant statement might remove a whole block.
The server therefore resolves anchors to Markdown blocks and builds comment windows. A window is a contiguous range of blocks that the model may replace. Overlapping comments share a window so two instructions about the same paragraph do not produce competing replacements.
This gives the model enough room to write coherent Markdown while keeping the boundary enforceable. The model can return more blocks, fewer blocks, or an empty replacement, but it receives no authority over text outside the window.
The distinction is subtle and important:
- Context includes the article brief, brand voice, keywords, topics, and the relevant region.
- Authority includes only the blocks assigned to the comment window.
Many AI editing systems conflate the two. They pass the whole article so the model can understand it, then hope a prompt such as “change nothing else” will be obeyed. We make the allowed scope structural instead.
4. One resolution run can handle several comments safely
Resolving comments one at a time would be simple, but it would be wasteful and could create contradictory edits. We batch the open comments into a single asynchronous run, subject to a clear per-run limit.
Each window receives a short label. The model returns the full replacement for every labelled region and nothing else. This is deliberately not a free-form conversation or a JSON patch. Markdown regions can contain quotes, lists, links, and line breaks; a small sentinel protocol is easier to parse without escaping the document into an unreadable payload.
The article is replayed as the model's earlier response, following a reconstructed brief. That framing makes minimal editing more natural: the model is continuing its own work in response to comments rather than rewriting an unfamiliar document from scratch.
The run happens in a background worker. A reviewer can close the tab and return later. Before the job starts, the system acquires a lock for the article so two tabs cannot resolve the same set of comments simultaneously. The UI checks that lock again when somebody begins editing, not only when the page first loads.
We also hash the article body at the start of the run. If the article changes before the proposed edits are reviewed, the result is refused. Block ranges computed against an earlier body must never be spliced into a newer one.
This is a recurring theme in the implementation: when safe intent cannot be reconstructed, the system stops and explains why instead of applying a plausible guess.
5. The output is a diff, not an automatic rewrite
When the worker finishes, it splices the proposed window replacements into a copy of the current article and calculates a block-level diff. The response includes change hunks, a projected content-quality score, unresolved comments, and a drift ratio that shows how much of the original document would be disturbed.
The editor uses the same accept-or-reject review surface as other revisions. A hunk is attributed back to the comments that produced it when possible, so the reviewer can connect the request to the result.
Only accepted segments are materialized into a new version, and the server performs that materialization. Keeping one server-side implementation avoids a subtle class of drift where the browser previews one combination of accepted changes but saves another after converting rich text back to Markdown.
The billing behavior follows the product behavior. If every window is orphaned, skipped, or returned unchanged, there is no useful review and no charge. Credits are consumed only when the run produces at least one replacement.
This review step is what turns inline comments from prompt shortcuts into a collaboration model. AI proposes; the editor remains the author of record.
6. Brand guidelines enter as structured context
Inline commenting solves where and how to change the article. It does not solve what “on brand” means.
Brand guidelines are often written for people. They mix positioning, tone, vocabulary, design principles, color specifications, examples, and restrictions in one document. Passing that entire file into every model call would be expensive and imprecise.
Seerly's Brand Hub turns the parts needed for generation into structured fields. For article generation and revision, the most relevant context includes:
- brand name, mission, and tagline when available;
- tone, style, formality, and a description of the brand voice;
- preferred vocabulary and words to avoid;
- target audiences;
- key differentiators and product language.
The content pipeline formats those fields into a compact brand context. The initial draft and later comment-resolution run receive the same core identity, along with the article's focus keyword, supporting keywords, content type, and target topics.
That consistency matters. If the first draft knows the brand voice but a later revision only sees “make this more direct,” the revised paragraph can drift into a different register. Brand-aware AI content generation needs the brand to be a standing input, not a decoration added during the first prompt.
We also preserve the absence of guidance. If a project has no completed Brand Hub, the prompt says no brand context is available. The system should not infer a brand voice from a domain name and present the guess as policy.
7. Text guidance and visual guidance are related, but not interchangeable
An article and its hero image share an editorial purpose, but they do not need identical brand inputs.
The article needs voice, audience, positioning, terminology, and search intent. The image needs the article subject, a suitable visual category, palette, image direction, logo treatment, composition, and accessibility text.
We keep those paths separate after they share the article context. This prevents rules such as “avoid this marketing phrase” from cluttering an image prompt, and prevents a visual preference such as “flat vector, no photographs of people” from being treated as article evidence.
The visual system uses three brand inputs:
- Brand colors, normalized into usable palette values.
- Image direction, a standing description of how the brand's imagery should look.
- The brand logo, including a profile of its tonality so it remains visible on the generated scene.
Image direction can be written by the customer or drafted from the visual material associated with the brand. A customer-authored direction is protected from automatic overwrite. Most importantly, the direction is included in generation only when it actually exists. The image model is told never to reconstruct a visual policy from the brand name, domain, or palette.
That distinction helps us incorporate brand images and brand guidelines without pretending they are all the same artifact. Reference material informs a durable visual direction; the final render uses that direction, the approved palette, and the actual logo alongside the article-specific brief.
8. The article, not the brand, decides what the image is about
A brand-aware image can still be a bad image for the article.
If a visual guideline favors abstract gradients, it should not cause an article about a five-stage architecture to lose the diagram that would explain it best. If the brand uses photography, that does not mean every technical subject should become a person looking at a laptop.
Our hero-image director reads the title, focus keyword, article body, and section headings. It scores possible visual categories and builds a structured image specification containing the prompt, composition, style, mood, palette, labels when appropriate, negative guidance, alt text, and filename.
The brand's image direction influences style and category choice, but it cannot contribute subject nouns. Subjects must come from the article. The direction answers how should this look? The article answers what should this show?
We apply a similar rule to text inside images. Proposed labels are checked against the article vocabulary. Generic headings can complete a layout, but a graphic should not invent claims or name concepts the article never discusses.
The director also considers recently used visual categories for the project. When two categories fit equally well, avoiding the latest pattern helps prevent every hero image from becoming the same purple dashboard or the same person-at-desk photograph.
9. Brand colors require composition logic, not prompt decoration
Adding a hex code to a prompt is not enough to create brand consistency.
Colors behave differently in a designed graphic and a photograph. A dominant brand color can govern shapes, connectors, and background accents in an illustration. Applying the same instruction literally to photography can create colored skin, skies, and objects that look artificial.
The pipeline resolves the palette after the visual category is chosen. Designed graphics receive explicit palette guidance. Photographic categories receive styling guidance that uses brand color in the environment and treatment rather than recoloring the subject.
Not every stored color is usable as a dominant value. If the primary color is unsuitable and a valid accent is available, the accent can be promoted. If the Brand Hub has no usable palette, the director's article-informed proposal is used. A neutral palette is the final fallback, not the first assumption.
This is one reason the generated image specification is stored. When a result feels off, we can inspect the selected category, palette source, article terms, and image direction instead of reducing the diagnosis to “the model ignored the brand.”
10. Logo handling is a rendering problem of its own
The logo is the most literal brand image, and it introduces its own failure modes.
A dark wordmark disappears on a dark corner. A JPEG logo can arrive with an opaque white rectangle. A square mark and a long wordmark need different width constraints. Asking an image model to reproduce a logo can alter the mark.
For supported generation paths, the system can provide the real logo as a reference and ask the model to place it. If that pass does not land, we keep the generated scene and fall back to deterministic compositing instead of regenerating the whole image.
The compositor analyzes both the logo and the target corner. It chooses a bare placement when contrast is safe, a subtle scrim when the corner is busy, or a plate when the mark needs a controlled ground. Sizing is bounded by height and width so different logo shapes remain legible without dominating the image.
The generated scene remains valuable even if logo placement fails. Logo retrieval, analysis, and overlay are best effort; they should not cause the entire content-generation job to fail.
11. The final image remains inspectable and reusable
The image service resolves the configured provider, builds the final prompt from the directed specification, applies a visual-diversity profile, requests the target aspect ratio, and handles provider failure explicitly.
Some practical safeguards matter more than they sound:
- a provider call has a fixed timeout so a retry endpoint cannot hold a connection indefinitely;
- a safety rejection can trigger one neutral, object-only fallback for legitimate sensitive topics;
- a generated image is checked and corrected to the expected hero ratio when necessary;
- the output is compressed to WebP for delivery;
- the stored asset retains its prompt, provider, model, alt text, generation time, and blob identity.
The article generation itself does not fail merely because the hero image could not be produced. Text and image have related contracts but separate failure boundaries. The UI can show the article and offer an image retry using the stored specification.
This metadata is useful for more than debugging. It supports repeatable regeneration, exposes what brand inputs reached the renderer, and lets future versions compare visual choices rather than treating each image as an unexplained binary.
12. What this changes for content teams
The result is not an AI writer with a few extra controls. It is a reviewable production workflow.
Writers can comment on the exact passage that needs work. Reviewers can add several requests and resolve them as one bounded run. The editor can inspect the proposed diff and reject any collateral change. Open comments survive version creation. Brand voice and target audience remain present during later revisions, not just the first draft.
On the visual side, the article defines the subject while the brand defines the treatment. Brand guidelines shape the palette and style. The approved logo is placed with contrast-aware rendering. The stored image specification makes the result explainable and retryable.
This also improves collaboration between roles. A content strategist can focus on the argument. A subject-matter expert can request precision at the sentence level. A brand lead can define standing visual direction once. Nobody needs to rewrite a giant prompt every time the document changes.
13. The engineering lesson
The most important lesson was that control does not come from a longer system prompt. It comes from boundaries in the data model and workflow.
The selection anchor tells us where the person meant. The comment window limits what the model may change. The body hash prevents stale work from landing. The diff makes the proposal reviewable. Versioning records the decision. Brand Hub supplies identity consistently. The image director separates subject from treatment. The renderer owns palette, logo, aspect ratio, and delivery concerns.
Each boundary is relatively small. Together, they make AI content creation behave less like a slot machine and more like an editorial system.
That is the direction we want for Seerly: generation that remains useful after the first draft, accepts precise human guidance, protects work that is already good, and carries the brand through both words and images without hiding how the result was produced.
