Positioning canon, docs metadata and repo polish - #315
Merged
Conversation
Split docs/contributing into six single-purpose guides so each owns one question and none restates another. Previously the audience definition and the product lexicon both lived inside the technical-writing guide, which scoped them to docs/ even though they govern the CLI, the web app, the README and the repo description too. That scoping gap is why several surfaces drifted apart. - audience.md (new): the canonical reader definition, promoted out of technical-writing.md because it sits upstream of everything else and governs product decisions, not just copy. - positioning.md (new): the promise, the canonical descriptions, which register each surface uses, which claims are safe to make, the answer to the privacy question, related projects, and an inventory of every place a description of Argus lives. - terminology.md (new): the product lexicon, promoted out of technical-writing.md so someone writing an error message doesn't have to open the docs-structure guide. - voice-and-tone.md: now governs every surface. Absorbs the terminal rules that were duplicated in CLAUDE.md, and scopes "Not a sales pitch" to reference docs so outward-facing copy can lead with the promise. - technical-writing.md: trimmed to building a docs page. - README.md: routes by job rather than listing files. Also records that Codex and ChatGPT Work are two separate OpenAI products rather than two names for one, per OpenAI's own documentation, and that Argus covers both through a single source because they appear to share a session format on disk. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The audience definition, the terminal-output rules and the product name styling were all duplicated here and in docs/contributing/, which is how they drift. Each is now a pointer to whichever guide owns it. Also widens the writing section from "Writing the docs" to "Writing about Argus", since the guides govern every user-facing word and not just the VitePress site, and lists what each of the five owns. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The site description and og:description still described Argus as software that "analyzes AI agent usage", and og:description called the audience "non-coders", which docs/contributing/ now rules out. Both now use the canonical one-liner. Fills in what was missing rather than wrong: - og:image, with a card built from the Activity screenshot. Shared links previewed with no image at all before this. - og:url, og:type, og:site_name, twitter:card and twitter:image. - A sitemap and a robots.txt pointing at it. - rel=canonical on every page. og:title, og:description, og:url and the canonical are now per page via transformPageData, so a link to /download no longer previews as the home page. Each page carries its own description in frontmatter, which feeds both the standard meta description and og:description. The home page deliberately has none so it falls back to the one-liner, keeping that copy in one place. docs/changelog.md is generated, so its frontmatter is emitted by the generator, above the banner comment since VitePress only parses frontmatter at the top of a file. scripts/og-image.ts (bun run og-image) rebuilds the card, so it can be regenerated when the screenshot changes instead of being a binary nobody can reproduce. Re-run it after refreshing the Activity screenshot. Also drops icon-192.png, icon-512.png and icon-512-maskable.png. There is no web manifest and nothing referenced them. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"Filtering what you see" and "Moving between views" read as instructions and make the reader parse a sentence to find the thing they came for. A noun phrase scans faster in an outline and doesn't lead the reader by the hand. Carves out conventional section names so Install, Settings and License stay as they are: the rule targets headings shaped like sentences, questions or gerunds, not every heading containing a verb. The heading-case bullet used "Get started" and "What the dashboard shows" as its examples, both of which the new rule rejects, so those are replaced too. 20 headings across 11 published pages still use the old style and are left for a separate pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Cuts it from 211 lines to 83. The removed 145 lines were CLI reference (flag tables for serve and index, the task-interpretation config, the sync walkthrough, systemd and launchd units) that already lives on the docs site and was drifting out of sync with it. Fixes what was wrong rather than just long: - "The macOS build is available now; Windows is coming soon" had been false since v0.1.22, which ships signed x64 and arm64 installers. - The lede led with "analyzes how you use your AI agents", the mechanism-first opening docs/contributing/positioning.md rules out. It now uses the canonical lede from there. - Nothing linked the demo, which is the fastest way to evaluate Argus without installing a binary. - Agents were listed in the old order and omitted ChatGPT Work. Friction signals are now marked Claude-only rather than implied for every agent, and the supported-agent line says "indexes" rather than "reads", which is reserved for describing what Argus does to your files. Headings follow the subject-naming rule. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The previous pass cut the README from 211 lines to 83 by removing CLI reference that duplicated the docs site. That was the right cut but it went too far, and took the evaluation material with it. Reference belongs on the docs site; whether Argus can see your sessions, and what it does with them, belongs here, because a reader decides that before clicking through. Compared against ccusage (~2,000 words) and AgentsView (~8,000), both of which lead with a supported-sources table and real usage examples. This lands at 149 lines. - Supported agents table with the actual read path per platform, from src/paths.ts. Surfaces two facts that were buried: Claude Chat comes out of the desktop app's cache rather than a transcript directory, and ChatGPT Work and Codex share one directory. - Architecture section: local SQLite, no service, no account; index as the sole writer; the optional model pass and how to point it elsewhere or switch it off; the Tauri tray shell. - Real CLI examples, checked against src/cli.ts rather than invented. - Development quickstart inline, so "can I build this" doesn't need a second file. - Features now mirrors the docs: the views in the left nav, in the same order and framing as docs/overview.md, each linking to the page that covers it. Adds Argus Hub, which the feature list had omitted entirely. - Two screenshot tables, alt text reused verbatim from the docs so the same image is described the same way in both places. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The guides in docs/contributing/ landed a few commits ago and the docs site, the largest surface we have, didn't follow them. - docs/index.md opened with "Argus analyzes your AI agent usage to help you be more productive with AI", the mechanism-first lede the canon rules out. It now uses the canonical lede. - ChatGPT Work appeared on zero pages, so a reader who lives in Work had no way to learn Argus covers them. It's now named on four. - supported-agents.md described Codex as "OpenAI's coding and knowledge work agent", merging two products the canon keeps distinct. Codex and ChatGPT Work are now separate rows, with a note that they share a directory so Argus reads both together. - Agent lists in four pages used the old order. They now run knowledge work, chat, coding. - The Cowork row put "macOS only" in the Windows column, which reads as a fact about Anthropic's product rather than a gap in Argus. It now says not yet supported. See #314. cli-reference.md is here only for its heading rename, because supported-agents.md links that anchor and the two need to move together. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Applies the heading rule from docs/contributing/technical-writing.md: headings name the subject, not the reader's task. "Filtering what you see" becomes "Filters", "Choosing a model provider" becomes "Model providers", and so on. README.md is here for one line: it linked tasks#choosing-a-model-provider, which this rename breaks, so the repoint has to land in the same commit. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The desktop app polls GitHub for new releases on a schedule, and the page whose whole job is enumerating what leaves your machine didn't mention it. That's the one network call Argus makes without being asked, so a reader auditing the question should find it there rather than discover it themselves. Says plainly that the Updates setting controls whether versions install on their own, not whether Argus checks: with it off it still checks and tells you. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It listed two, "voice and tone, and technical writing", so anyone following the pointer missed audience, positioning and terminology. Also widens the scope line: the guides cover the README, the repo description, package metadata and release notes, not just pages under docs/. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The published package.json carried only name, version, description, bin, files and optionalDependencies. npmjs.com rendered a bare description with no link back to the project, no license and no README. Adds repository, homepage, bugs and license to the launcher and to every platform package, plus keywords on the launcher, and ships README.md and LICENSE so the package page renders. Keywords are deliberately short; a long tail of near-duplicates reads as padding. The root description was still the old positioning copy, so it's now the canonical one-liner from docs/contributing/positioning.md, which is where the published description comes from. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Argus reads your agent sessions, so a security policy is the file a careful reader looks for and there wasn't one. Reports go through GitHub's private vulnerability reporting rather than an email address, so there's no mailbox to maintain. Scope names what matters most given what Argus touches: session data leaving the machine, stored API keys, the local web server and the desktop front-door port, and crafted session files during indexing. Also states what Argus already does, so a reporter can judge whether something is a real finding: read-only indexing, nothing uploaded without a Hub, text staying local, where keys live per platform, the update check, and how release artifacts are signed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Twelve commits, reviewable in order. Split by concern rather than by file, so each one stands alone.
What's here
A canonical source for how we describe Argus.
docs/contributing/was two guides scoped todocs/, which is why several surfaces had drifted apart: four different one-liners, and anog:descriptioncalling the audience "non-coders" that nothing governed. It's now six single-purpose guides covering every user-facing word, including the CLI and the repo description.CLAUDE.mdpoints at them instead of restating them.Docs site metadata. Shared links previewed with no image at all. Adds
og:imagewith a card built from the Activity screenshot, plusog:url,og:type,og:site_name,twitter:card, a sitemap,robots.txtandrel=canonical. Social tags are now per page, so a link to/downloadno longer previews as the home page. Every page carries its own description.README. 211 lines to 149. Removed CLI reference that duplicated the docs site; added a supported-agents table with real read paths, an architecture section, verified CLI examples and a dev quickstart. Fixes a "Windows is coming soon" line that had been false since v0.1.22.
Docs pages brought in line with the canon. ChatGPT Work went from zero mentions to four pages. Codex had been described as "OpenAI's coding and knowledge work agent", merging two products. Twenty task-shaped headings renamed under a new rule, with inbound anchors repointed in the same commits.
Privacy page now discloses the update check, the one network call Argus makes unprompted.
npm metadata. The published package had no
repository,homepage,licenseor README, so npmjs.com rendered a bare description with no link back.SECURITY.md, routed through GitHub private vulnerability reporting.Checks
692 tests pass,
typecheckclean, docs build clean at every commit so no dead anchors mid-history. Security review found nothing: the code surface is six files and none takes untrusted input.Not included
Release notes are still raw PR titles, mirrored onto the public changelog. Deferred deliberately.
Follow-ups: the demo site (
web/index.html) has no title or description, and #314 covers Cowork on Windows.