# Artifacts: reports, specs and pages

> Publish weekly updates, launch notes, specs, mocks and small sites to your organization: formats, keys and versions, spaces, folders, icons and dates, images, revising an artifact someone else published, who sees what, and locking.

An artifact is a page you publish for people in your organization: a weekly update, a launch update, a spec, a mock, a deck, a small site. Hillclimb keeps every version, files it in a folder, orders it by the day it covers, and shows it in the console under Artifacts (`/artifacts`), across all your organization's trees. Artifacts never change any outcome's status. They aren't evidence.

Hillclimb doesn't write or schedule reports. You do, when your person asks or on whatever schedule they set up for you.

## Publishing

`publish_artifact` with a `title`, `format` and the content:

- **markdown**: send it as `content`. Hillclimb renders it in the console's own style, GitHub-flavored like all markdown in Hillclimb (tables, task lists, images, inline video). Raw HTML in markdown is dropped, never run. This is the default for reports.
- **html**: one self-contained page as `content` (inline CSS and JS are fine).
- **bundle**: any static site. List every file in `files` (with `index.html`).

HTML and bundles run in a sandbox on a separate origin. They can run scripts and load from https, but they can't read cookies, use storage, or call Hillclimb as the person viewing them. Link goals and outcomes with the `url` their tool results carry: in the console, people open them in the side panel without leaving the report, and other Hillclimb links open in place. Other sites open in a new tab, as do Hillclimb links on a share link. You needn't set `target`; relative links and `#anchors` stay in the page.

## Keys and versions

Hillclimb gives each artifact a `key`: 8 random lowercase letters and digits, like `k3x9q2ma`. The key is the artifact. Its url reads `/artifacts/<org>/<slug>~<key>`, where the slug is the title made readable (lowercase words and dashes, at most 60 characters). The slug is only for people: it isn't unique, it follows the title, and only the key finds the artifact, so two people can both publish "Weekly update" and nobody owns a name. Tools take the key or the whole `slug~key` from a url.

Publishing without `key` makes a new artifact and returns its key. Keep it: publishing again with that `key` adds a version. To revise something you didn't just publish, find it with `list_artifacts` (its folder narrows it) and pass its key. A publish that failed before it returned made nothing, so retry it as is; one that returned a key made the artifact, so retry with that key. Say what changed in `note`.

A new version keeps everything you leave out: its folder, kind, icon, tone, summary, `asOf`, `periodEnd`, subjects, template and visibility stay as they are, so a revision sends the key, title, format and content (and `note`) and nothing else it doesn't mean to change. Pass a field to change it; `folder: ""` moves it to the top level. `move_artifact` changes the folder, title, date, icon or tone without a new version.

A new week is a new artifact, not a new version: next week's update sits beside this week's in the same folder. A version is a correction to the same thing, or the next run of one living page (a daily readiness report, a changelog).

`get_artifact` returns every version and the source of the one shown (the latest, or any earlier one by `version`): the markdown, the HTML page (a bundle's `index.html` too), or a deck's slides. Each of its `files` carries a `url` that returns that file's exact bytes for an hour (`filesExpireAt`): GET them for a bundle's stylesheets, scripts and images, or a page too large to come back inline. Any member, contributors included, can revise a shared artifact (add versions, move, rename); archiving one is for its publisher and owners, admins and editors, and a private one is only its publisher's. To revise someone's artifact, start from that source, change only what you were asked to, and publish with the same `key`, keeping the files you didn't change (the same `sha256` needs no upload), so the next version keeps their content and styling. Never rebuild a page you haven't read.

## Spaces, folders and dates

The console files artifacts in two places: **spaces**, the shared top-level folders everyone in the organization sees (like `Engineering` or `Sales`), and each person's **Private**, which holds their private artifacts in folders of their own. `folder` files an artifact: its first part is the space (`Engineering/Runbooks/GCP`), or the Private folder when it's private. Folders go three levels deep at most, a space, a folder and one below, so put finer detail in the title. Older, deeper folders still read and keep working when you add versions. File into the space that fits rather than starting a new one; `list_artifacts` shows the spaces and their folders.

`set_folder` makes a folder before anything is in it (at the top level that's a new space), gives a folder an icon and tone, renames it, which moves everything inside (each artifact keeps its link; links to the folder itself follow the new name), or removes an empty one with `remove: true`. Any member can make and dress a shared folder; renaming a shared one moves other people's artifacts, so owners, admins and editors do that, and they or the folder's maker remove one. With `private: true` it works on your Private folders.

Spaces, folders and artifacts each wear an `icon` and `tone` from Hillclimb's set. `list_artifact_icons` searches the icons by name or alias ("finance", "incident", "launch"); tones are gray, blue, teal, green, orange, red, purple and pink. Without one, an artifact's icon comes from its kind and a folder's from its name. Pick icons that say what's inside, and keep one tone per space so it reads as a set.

`asOf` is the day (or the start of the period) the artifact covers, and `periodEnd` the end. Folders list newest `asOf` first, so set it even when you publish late. `list_artifacts` shows a folder's artifacts and subfolders (`visibility: "private"` for your Private), sorts by `asOf`, `updated` or `title`, and pages with `offset`; its `latestUrl` always opens the newest one. `move_artifact` changes the folder, title, date, icon or tone, and `archive_artifact` takes one out of listings.

## Images and other files

List images, CSS or scripts in `files` with their `path`, `type`, `size` and `sha256` (lowercase hex of the bytes), and reference them by relative path: `![Burn-up](images/burnup.png)`. Files Hillclimb already has are skipped. The rest come back in `uploads`: PUT each file's exact bytes to its `url` with the headers given, then call `commit_artifact` with the `upload` id. Up to 10 MB a file, 50 MB and 200 files a version, 5 MB inline. If you can't make HTTP requests, publish markdown or one HTML page inline and use https image URLs.

## Who sees it

Every member of the organization sees it, in its space, unless you publish with `visibility: "private"`, which keeps it to you in your Private. Anyone who can see it can read its source. Any member can add versions to a shared artifact and move or rename it; only its publisher, or an owner, admin or editor, can archive it. A private one is only its publisher's.

`lock_artifact` locks a document under control, such as a policy or a compliance record: while it's locked nobody, its publisher included, can add versions, move, rename or archive it, and `get_artifact` shows `locked` with who locked it and when. Members still read it and its links keep working. Its publisher, an owner or an admin locks it, and unlocks it with `unlock: true`. Asked to change a locked artifact, tell the person it's locked and who can unlock it, or publish your changes as a new artifact without `key`.

## Slide decks

A deck is data, not a page: `publish_artifact` with format "slides" and `slides`: [{ `body`, `notes`, `layout` }], plus a `theme`: hillclimb (Hillclimb's look and the default), midnight (dark) or paper (warm, editorial). A deck keeps its theme whatever the viewer's light or dark setting, so it looks the same on every screen and projector; pick midnight when you want a dark deck. Bodies are markdown, or HTML with `format`: "html" for charts and custom layouts; an h4 above a heading is a small kicker, and HTML slides can use the report kit's classes (kpis, chip, grid and card, bar). One idea per slide, big type, the detail in notes. Hillclimb renders the deck into one page that presents on its own: arrow keys and swipes, F for full screen, N for speaker notes, and it prints one slide per page and stacks the slides on a phone. Layouts: "title" (the first slide's default), "section", "content" (the default), "split" (two columns; a line with only `+++` divides them, and a heading that opens the left column spans both unless the right column opens with one too), "center", "full" (one image edge to edge). `get_artifact` gives the slides back as data: change the ones that need it and publish the whole deck again.

## Templates

`list_artifact_templates` lists the built-in templates (weekly update, what I got done, launch update, release readiness, roadmap review, tree health, spec, changelog, deck, blank page, and more), your organization's, and your own. `get_artifact_template` gives one: the recipe (which tools to call, in order, and what to leave out), the starter to fill in, the folder to publish in, and a `templateRef` to pass as `template` when you publish, so the report records which version of the template it followed. When a person asks for "our weekly update", follow the template rather than inventing a format. The built-in internal reports (stand-up, weekly, retro, postmortem, launch and investor updates, and the like) share one design system, Hillclimb's report kit: keep the starter's `<head>` and `<style>` exactly, write only the body with the kit's components (masthead, KPI tiles, outcome rows with status chips, decision callouts, tables, timeline), and use color only for status. Docs like a spec or decision record stay plain markdown; customer- and investor-facing pages carry the company's own look.

People save their own formats with `save_artifact_template`: a recipe, a starter and where reports go. A new template is private to whoever saved it; saving it again with `visibility` "organization" shares it with everyone there, and only its owner can change that.

## Sharing outside the organization

`share_artifact` makes an unlisted link that shows the artifact's latest version to anyone who has it, without signing in: investors, a customer, another company. Name it after who it's for; it can expire. It's outward sharing, so confirm with the person first and pass `confirmedWithPerson: true`. `list_artifact_links` shows each link's views; `revoke_artifact_link` stops one. Only whoever published an artifact, or owners and admins, share it. Archiving an artifact stops its links too.

## Limits

Up to 10 MB a file, 50 MB and 200 files a version, 150 slides a deck, 5 MB inline, and a storage limit per organization that `get_usage` reports (`artifacts`), counting each file once however many versions share it. Archived artifacts are deleted for good 30 days after archiving. A publish over a limit is refused with the limit and what to do: compress or split a large file, combine small ones, or publish parts as separate artifacts.

## Releases and the tree

An artifact about a release, with `subjects` [{ tree, release }], shows on that release (`get_release` and the roadmap's release panel list its `writeUps`). `record_launch` with `artifact` puts the launch update first among the launch links. Reports about one person's work use `list_changes` with `actor`, `since` and `until`.

## Linking

`url` opens the artifact and `versionUrl` that exact version. Give people the link. Add an `#anchor` to point at one place in it: `url` + "#pricing" opens the artifact scrolled to its pricing section, in the console and on a share link. Markdown headings get GitHub's anchors ("## Next steps" is #next-steps; a repeat gets -1), and an HTML page's anchors are its own `id`s, so give sections people will point at a short, stable `id`. When someone follows an anchor inside an artifact, the address bar shows it, so they can copy the link from where they are. Inside a report, link goals, outcomes, plans, releases and roadmaps with the `url` their tool results carry (see the climbing guide). `subjects` records what it's about, e.g. `[{ "tree": "acme/7f3k2m9q", "release": "c5j8u2fd" }]` (keys, or `slug~key` from a url).
