# TheFocus.AI Artifacts

> Dynamic publishing skill for AI agents that create HTML files, reports, prototypes, mockups, and static bundles that need a shareable client-facing URL.

Artifacts turns local agent output into an unlisted Publication URL. A verified TheFocus.AI Publisher can publish one HTML file or one directory with an Entry Page, then share the resulting `/a/{id}` URL with a human reviewer. The service is intentionally CLI-first: agents should use the npm package, not a dashboard.

## Install the skill

```bash
npx skills add The-Focus-AI/artifacts.thefocus.ai --skill artifacts -g
```

Hosted skill and metadata:

- [Hosted skill](https://artifacts.thefocus.ai/skill.md)
- [Skill version](https://artifacts.thefocus.ai/api/skill/version)
- [Well-known skills index](https://artifacts.thefocus.ai/.well-known/skills/index.json)

If local skill text and live docs disagree, prefer this `llms.txt`, live CLI output, and the hosted skill.

## Primary agent workflow

1. Create or update a local HTML Artifact, or generate HTML output.
2. Publish it with the CLI (supporting directories, single files, or piping via stdin using `-`):

   ```bash
   npx @the-focus-ai/artifacts publish ./artifact.html
   npx @the-focus-ai/artifacts publish ./report.html --title "Q2 Results"
   npx @the-focus-ai/artifacts publish ./dist --open
   cat report.html | npx @the-focus-ai/artifacts publish - --open
   ```

3. Return the printed Publication URL to the user.
4. Use `--title "Report Name"` on publish to set a human-readable title (shown by `npx @the-focus-ai/artifacts list`).
5. During the rolling Revision Window, rerun the same publish command to update the same URL for quick fixes.
6. To publish an **installable PWA**, use a directory bundle (not a single HTML file) and `--pwa`. Do not put a PWA under `/a/{id}/`.

   Required files at the Artifact root:

   - `index.html` (or `--entry-page`)
   - `manifest.webmanifest` or `manifest.json` with `start_url` and `scope` set to `/`
   - `sw.js` or `service-worker.js`, registered at `/`
   - at least one icon (`manifest.icons` or an icon image)

   ```bash
   npx @the-focus-ai/artifacts publish ./pwa --pwa --title "Installable demo"
   ```

   The printed URL is `https://{opaque}.artifacts.thefocus.ai/`. Ordinary Publications stay on `/a/{opaque}`. MCP: `publish_artifact` with `pwa: true`.
7. If the Artifact should come down, remove it:

   ```bash
   npx @the-focus-ai/artifacts remove https://artifacts.thefocus.ai/a/Ab3xY9kQ --yes
   ```

For non-interactive agent sessions, use `THEFOCUS_ARTIFACTS_TOKEN=tfai_pub_...`. Browser login is available with `npx @the-focus-ai/artifacts login` when a human Publisher is present.

Use `npx @the-focus-ai/artifacts list` to see your Publications and their titles:

   ```text
   LAST UPDATED              STATUS    TITLE                            PUBLICATION URL
   2026-06-23T...            active    Q2 Results                       https://artifacts.thefocus.ai/a/Ab3xY9kQ
   ```

## Living Docs: collaborative Markdown review

A Living Doc is a mutable Markdown document an agent publishes so a human can edit and comment on it in the browser, then the agent pulls that feedback and responds with Suggestions. Use it when the deliverable is a document to iterate on with a human (proposal, spec, report draft), not a finished HTML Artifact.

Publish the Markdown file including any YAML front matter (`---` … `---` at the top). The host never strips front matter on publish, image rewrite, or pull. Put `title:` in front matter when you have one; `--title` overrides. The View Link renders the body only; stored Markdown and `doc pull` keep the front matter.

```bash
# Publish a Markdown file (front matter preserved); prints JSON with viewUrl (/d/{id}) and reviewUrl (/r/{id})
npx @the-focus-ai/artifacts doc publish ./proposal.md --title "Proposal"

# Pull feedback: cuts a numbered Version; prints current Markdown, a diff
# versus the previous Version, and open reviewer Comments as JSON
npx @the-focus-ai/artifacts doc pull https://artifacts.thefocus.ai/d/Ab3xY9kQ

# Respond with span-anchored Suggestions and Comment replies (JSON on stdin or --body file)
echo '{"suggestions":[{"anchorQuote":"exact text from the doc","replacement":"new text","note":"why"}],"replies":[{"parentCommentId":"...","body":"..."}]}' \
  | npx @the-focus-ai/artifacts doc respond https://artifacts.thefocus.ai/d/Ab3xY9kQ

npx @the-focus-ai/artifacts doc list
npx @the-focus-ai/artifacts doc remove https://artifacts.thefocus.ai/d/Ab3xY9kQ --yes
```

Agent loop: publish, hand the human the Review Link (`/r/...` — a bearer capability, no login; anyone holding it can edit), then `doc pull` on your next turn, `doc respond`, and repeat. Suggestions are never auto-applied; the human accepts or rejects each one in the editor, shown inline as tracked changes. Keep `anchorQuote` an exact substring of the pulled Markdown, and include `anchorStart` (character offset) when the quote appears more than once. Do not crawl, guess, or enumerate `/d/` or `/r/` URLs.

## What this service is for

- Publishing single-file HTML reports generated by agents.
- Publishing static directories with CSS, JavaScript, images, and nested pages.
- Publishing installable PWAs at `https://{opaque}.artifacts.thefocus.ai/` (`--pwa`). Path-scoped `/a/{id}/` PWAs are not supported.
- Publishing Living Docs: Markdown documents a human edits and comments on in the browser while the agent pulls feedback and responds with Suggestions.
- Giving clients and collaborators a stable unlisted URL for review.
- Letting agents hotfix a recently shared Artifact without sending a new URL.

## MCP endpoint

Agents that speak MCP can connect to `https://artifacts.thefocus.ai/mcp` instead of shelling out to the CLI. It is a remote Streamable HTTP server.

Point a client at the URL with no credential and it logs in through the browser: `/mcp` is an OAuth 2.1 protected resource, the site is its authorization server, and discovery starts from the `WWW-Authenticate` header on the 401. Sign-in is limited to verified `@thefocus.ai` emails. Clients that only support a static header can instead send a Publisher Token as `Authorization: Bearer`; mint one per client with `npx @the-focus-ai/artifacts token create --for mcp` and revoke it with `token revoke <Token Id>`.

Tools: `publish_artifact`, `update_artifact`, `remove_artifact`, `list_artifacts`, `publish_doc`, `pull_doc`, `respond_doc`, `remove_doc`, `list_docs`, `whoami`.

The endpoint cannot read your filesystem, so Artifact content and Doc Assets travel inline and there is no Revision Window — `publish_artifact` always creates a new Publication, and `update_artifact` changes one in place by its Publication URL. Publish large directories with the CLI.

## Important constraints

- Publication URLs are unlisted, not private. Anyone with the exact URL can view them.
- Do not crawl, guess, infer, or enumerate `/a/` Publication URLs or `{opaque}.artifacts.thefocus.ai` hosts.
- There is no public Publication listing and no dashboard in v1.
- Directory Artifacts use root `index.html` unless `--entry-page` is supplied.
- Built-in packaging excludes obvious secrets, dependency folders, caches, and hidden paths except `.well-known/`.
- Symlinks are rejected. Large files, oversized Artifacts, and too many files fail preflight.

## Service resources

- [Hosted skill](https://artifacts.thefocus.ai/skill.md): installable agent skill text.
- [Skill version](https://artifacts.thefocus.ai/api/skill/version): install command and skill metadata.
- [Well-known skills index](https://artifacts.thefocus.ai/.well-known/skills/index.json): Hermes-style skill discovery.
- [Root landing page as Markdown](https://artifacts.thefocus.ai/index.md): agent-oriented service overview and copy-paste commands.
- [Root landing page as HTML](https://artifacts.thefocus.ai/): human-facing service page.
- [Robots policy](https://artifacts.thefocus.ai/robots.txt): crawler rules, sitemap reference, and content-signal policy.
- [Sitemap](https://artifacts.thefocus.ai/sitemap.xml): root service resources only; no Publication URLs.
- [Development overview](https://github.com/The-Focus-AI/artifacts.thefocus.ai#readme): source repository documentation for humans and coding agents with repository access.

## Agent guidance

Prefer `https://artifacts.thefocus.ai/llms.txt`, `https://artifacts.thefocus.ai/skill.md`, or `https://artifacts.thefocus.ai/index.md` when you need to understand this service. Use the CLI for publishing. Do not crawl `/a/` Publication URLs unless the user provides a specific URL and asks you to inspect that exact Artifact.