Using Living Artifacts

A living artifact keeps its numbers in one place, so a dashboard, a written report, and anything else that quotes them can be kept in sync. This guide covers creating one, changing its figures, refreshing it from its source, and quoting it from other artifacts. It builds on Creating Artifacts.

How a living artifact fits together

A living artifact is a small set of ordinary artifacts that work together:

• The dataset is a spreadsheet artifact with one row per figure, called a key. Every number the living artifact quotes is stored here once, together with its date, its status, and where it came from.
• The views are filled from the dataset: usually a readable document and an interactive page. Each view carries the link Values inside the markers are filled from a dataset. Open the dataset, which takes you back to the dataset.

In a view's text, each filled figure sits between a pair of markers, such as <!--k:repo.issues.open.total-->42<!--/k-->. You see the markers only while editing the view; when you read it, you see just the figure. When the views are updated, only the values between markers change. Everything you write outside them, such as headings, commentary, or a notes section, is kept.

To list every dataset in your workspace, choose Spreadsheets in the Artifacts gallery: a dataset is a spreadsheet, and its title ends in (dataset). The tags Upstream uses to link a living artifact together, such as dataset, view:readable and view:interactive, are managed for you, so the gallery's tag filter does not list them.

What the dataset's columns mean

Each row has one of five statuses:

• final: settled.
• provisional: may still change.
• estimate: estimated rather than counted.
• open: not known yet. Views show not found in its place.
• stale: the source used to produce this figure and no longer does. The row is kept rather than deleted, and views still show its last value.

Creating a living artifact

Repository status from GitHub issues

Before you start, your organization owner needs to connect a repository in the GitHub Issues section of the Upload page, and its issues need to be imported. See Uploading Documents. Once the repository is connected, any member can create a status.

1. Open Upload and find the GitHub Issues section.
2. Choose Import issues if the last import is not recent. The status is built only from issues already imported; creating it does not import anything. Import Open and closed issues if you want the closed-issue figures to be complete.
3. Choose Create repository status. TurnkeyGTM builds the dataset and two views, then opens the dataset.

Your library gains three artifacts: Repository status: owner/name (dataset), Repository status: owner/name (the readable view), and Repository status: owner/name (interactive).

The dataset records:

• Open issues by group. Every open issue is counted in exactly one group: the first of these labels it carries, checked in this order: bug, enhancement, documentation, tracking, sprint-planning, backlog. An issue with none of them is grouped by its area: label (the alphabetically first, if it has several). Anything else is unlabelled, even if it carries other labels. The groups add up to the open total, and the unlabelled group is always shown, even at zero, because its size tells you how much of the backlog nobody has sorted.
• Movement. Open issues touched in the last 7 days, open issues untouched for 90 days or more, and issues opened and closed in the last 30 days. These windows are measured from when the status was created or last refreshed. Closed-issue figures count only issues that have been imported.
• Two issues worth a look. The oldest open issue (number, title, link, and age in days) and the most recently updated open issue (number, title, and link).

Each repository has one repository status. Choosing Create repository status again opens the existing one instead of making a copy. When an issue changes on GitHub, the next import or refresh updates its source in place: the old wording is replaced, not kept alongside the new.

Site overview from a Content Spy crawl

The site overview is available only in workspaces connected to Content Spy, the TurnkeyGTM website crawler and reviewer. If the Content Spy crawl card does not appear on your Upload page, the site overview is not available in your workspace.

1. Crawl the site in Content Spy. TurnkeyGTM reads the crawl Content Spy has stored; it never crawls the site itself.
2. On the Upload page, in the Content Spy crawl card, enter the site's target slug and choose Import crawl.
3. Choose Create site overview. TurnkeyGTM builds the dataset and two views, then opens the dataset.

The dataset records the pages crawled, the pages in each section (grouped by the first part of each page's web address, with the home page as Home), the first page found for key sections (pricing, blog, docs, about, solutions, customers, security, and integrations), review findings by severity, the average page score, the words across crawled pages, the third-party vendors embedded in the pages, and the date of the last crawl. Every page lands in exactly one section, so the section counts add up to the total. A key section that reads not found was not reached by the crawl.

From chat

Ask chat for what you need:

• "Create a live dashboard for our Q4 pipeline review." Chat defines each figure once as a row in a new dataset, then writes one to four views from it: a readable document, an interactive page, or both. Include the figures in your request. A figure chat cannot establish is recorded as open.
• "Write a draft release-readiness summary quoting the existing repository status dataset." Chat can author another view for your purpose using the existing keys and markers. This keeps the same dataset; it does not create a new source binding.
• "Create a repository status." Chat uses the repository in your saved GitHub connection. Import the issues from the Upload page first; chat cannot import them for you.
• "Create a site overview for acme-site." Where Content Spy is connected, chat imports the crawl with that target slug and builds the overview.

Changing a figure and updating the views

1. Open the dataset.
2. Click the cell you want to change, type the new value, and click outside the cell. Edits save automatically.
3. Choose Update linked views. Any edits not yet saved are saved first.

The message tells you what happened, for example Updated 2 linked views: 1 value changed or Linked views already match the dataset. No change. If a view cannot be updated, the message says why. A concurrent edit rejects that write; an unknown outcome needs inspection before another attempt. Review the latest view before updating again.

A few rules keep the views accurate:

• Change figures in the dataset, not in a view. The next update replaces anything typed between a view's markers.
• If you delete a pair of markers, that figure becomes ordinary text and stops updating.
• When you change a value by hand, update its as_of date and status too. On a dataset that refreshes from a source, also set its source to manual (see the next section).
• To add a figure, choose Add Row and give it a unique key, a label, and a unit. To show it in a readable view, edit the view and add a marker for the key where the figure should go, such as <!--k:your.key-->…<!--/k-->, then choose Update linked views.
• Each key must be unique. If two rows share a key, the update stops and names the duplicate.

Refreshing from the source

Site overviews and repository statuses are bound to the source they were built from, so their datasets have Refresh from source. It re-reads the source, recomputes every figure, merges the results into the dataset, and updates its child views. A linked view also offers this action when its parent is verified as a supported bound dataset. From a quoting artifact, the same recorded action includes that requesting artifact; unrelated quoting artifacts are left for review.

• Repository status: re-imports open and closed issues through your organization's saved GitHub connection. Only issues that changed since the previous refresh finished importing are fetched; the first refresh fetches them all. A very large repository can take more than one refresh to catch up, and each refresh continues where the last one stopped.
• Site overview: re-reads the latest crawl stored in Content Spy. It does not crawl the site, so run a new crawl in Content Spy first when you want fresh figures.

Refresh can enqueue source ingestion and incur AI processing costs. It is a source import, separate from the deterministic Update from dataset action.

How a refresh treats your dataset:

• A figure the source produces again replaces the old value, and the old value moves into supersedes with its date.
• A row whose source is manual belongs to you: no refresh ever changes it. Set manual on any figure you edit or add by hand. Otherwise the next refresh can put the source's value back, keeping yours in supersedes.
• A figure the source no longer produces stays in the dataset, marked stale.

Every refresh records its phase and outcome. A message reports it, and the Last refresh line beside the button keeps it:

The Last refresh line on a linked view reports its parent dataset’s run, including the source, imported-record counts when available, and errors. It also shows agent when chat ran the refresh, scheduled when it ran as one of the due refreshes, and due when an approved, unpaused action has remaining allowance and its cadence has elapsed. No change describes facts, while evidence and interpretation have separate states. Expand Upkeep on the dataset to inspect recent run IDs, phases, source job receipts, evidence and per-view outcomes.

Setting a refresh cadence

Bound datasets have a Refresh menu beside Refresh from source, with manually (the default), daily, weekly, and monthly. Saving this setting creates a proposal and clears previous execution approval. Existing cadence settings do not approve automatic spending.

Open Upkeep, inspect the source/view scope and any exact narrative span, choose a finite run allowance, then select Approve upkeep. Approval requires the organization owner and a fresh native sign-in after the proposal was saved; renewing an existing agent token is insufficient. Google accounts confirm through the native sign-in popup. Email/password owners save the proposal, sign out and sign in again, then approve within five minutes. Approval is tied to that actor and the saved connection. Pause upkeep stops new work. An active or unknown run blocks another action; inspect its source jobs and affected artifacts before selecting I inspected this run; clear approval. Inspection clears approval, and never replays the original request.

The app does not install a schedule. An operator may separately authorize a native external trigger using the existing protected, renewable MCP session. That trigger and chat's refresh what is due call the same guarded action. The finite pilot bounds source requests, retained input size, ingestion jobs, views and review rounds; the control shows the limits. This is separate from general subscription metering. Source and interpretation calls can incur costs. Large or incomplete imports stay partial; this pilot is not unrestricted repository or website upkeep.

A custom dataset created from chat cannot have a cadence, because it has no source to refresh from. A new view over an existing bound dataset continues to use that dataset’s source; choose cadence on the dataset itself.

Quoting a dataset from other artifacts

Any artifact can quote a dataset's figures, such as a board update that quotes your repository status. Ask chat to write it, for example: "Write a one-page board update that quotes the open-issue figures from the repository status dataset." Chat places each figure between markers, tags the new artifact dataset:<id> (where <id> is the last part of the dataset's web address), and fills it once when it is created. The artifact then shows the same Open the dataset link as a view.

Keep an existing draft summary: on a compatible backend, an authenticated API client can call POST /api/v1/artifacts/{org_id}/{artifact_id}/attach-dataset with dataset_id and the draft's current expected_revision. This links the same draft without recreating it or changing its text, notes, citations or publication history. Both artifacts must belong to the workspace, and an existing different parent cannot be replaced. Attachment alone fills nothing and approves no upkeep; it makes the draft a quoting artifact, not an automatically updated child. There is no attachment button or chat/MCP attachment tool yet. An older backend refuses the action; never substitute a tag edit or legacy PATCH. On conflict or an uncertain response, read the latest artifact before taking further action rather than automatically retrying.

After that, a quoting artifact changes only when someone decides it should:

• On the dataset, a line reads Quoted by 3 other artifacts, followed by all current or by the artifacts that are out of date and how many values each is behind. Choose Update it, or Update all followed by the number when several are out of date.
• On a child view or quoting artifact, choose Update from dataset to update that artifact alone. This fills marked facts from saved dataset rows without AI synthesis; prose outside the markers stays as written.
• Update linked views and Refresh from source on the dataset update its child views. A refresh requested from a quoting artifact also fills that requesting artifact when needed. Other quoting artifacts are never silently updated; review their stale values on the dataset.
• Ask chat what a change reaches, such as "What does changing the open-issue count affect?" Chat lists every artifact that quotes that figure without changing any of them.

Updates are deliberate because a quoting artifact is often someone's finished document, such as a brief already shared with a customer. It should not change unless someone decides it should.

Reviewing interpretation with supporting evidence

Facts and interpretation need separate upkeep. A GitHub issue body or comment can change what a summary should say even when every metric key stays the same. No change is a fact-update result, not a semantic review.

For a supported draft summary, choose Refine in Chat and ask for the review you need, for example: “Read the retained issue evidence and reconsider the release risks in this summary; preserve its fact markers.” Chat can search and read bounded retained source evidence with citations, without enabling optional screening. The selected artifact remains the only edit target. Reading evidence never grants permission to edit the source, another artifact, or the dataset, or to create, refresh, or set cadence during that bound conversation. See Creating Artifacts for supported draft types and size limits.

An agent can propose a review instruction, selected retained source IDs and an exact unique narrative span (or explicitly the whole supported document). The owner inspects and approves that scope in Upkeep. Headings do not grant edit authority. Only relevant changed evidence triggers review; unchanged inputs and known adapter-only timestamp changes skip inference. Review can conclude that no rewrite is needed. Text outside the approved span and old citation identities are preserved by the server.

For a one-off GitHub-backed review, the proposal can select retained sources while cadence stays Manual. Configure the exact view, source IDs and span through the existing agent/API proposal, then inspect and approve a finite allowance on its dataset with a fresh owner sign-in. Review retained sources reads only those already-ingested sources and updates only the selected view; it does not fetch GitHub, import a repository, recompute repository totals or enable scheduling. If newer evidence is needed, separately import the complete selected issue through the existing one-issue ingestion path and wait for that job to finish before review. A source update can consume embedding/extraction work separately from the review allowance.

Retained review follows full-source pages, with a total ceiling of 96,000 characters, 128,000 UTF-8 bytes and 32,768 evidence-context tokens across at most five selected sources. Missing pages, incomplete capture, changed source revisions or an exceeded ceiling leave interpretation review-needed, never reviewed from an excerpt. The draft limit is unchanged. Saving another cadence/proposal clears the approval; changing the cadence dropdown alone does not preserve an exact-span proposal. Older backends reject the new source-mode field; clients must not omit it or fall back to repository refresh.

The run keeps a bounded retained-evidence manifest and the exact source passages consumed by a review. This is a checkpoint of retained evidence, not a claim that every remote source is current or that the interpretation is correct. A repeat refresh does not clear pending review. Processing, isolated, unavailable or partial evidence cannot certify reviewed interpretation. Automatic narrative review retains the existing complete-draft text limit; published, HTML, structured or oversized targets need manual review. Refresh does not create a publication-version snapshot or republish a hosted copy.

Fill, refresh, cadence, approval and pause controls save pending edits first. A failed or uncertain save cancels the action. If you type while an action or its readback is running, the editor keeps your local draft and blocks further saves and updates instead of replacing it or silently rebasing it. Keep the tab open or copy your edits, then use Review latest in a separate tab. An action or readback error does not automatically retry a mutation.

A refresh from a linked or quoting view is confirmed only when the run reports that exact view as changed or unchanged. A missing, failed or unrecognized per-view result leaves the update unconfirmed and keeps the draft; the dataset's No change result alone is not confirmation. Inspect the recorded run and latest view rather than replaying the action.

Refresh and cadence changes require a compatible backend. Operators must release the guarded backend first, then upgrade browser/MCP clients before enabling any external trigger. An older backend refuses new action routes; an older client missing the required request identity must upgrade. Neither case grants automatic spending approval or permits retrying through an older endpoint.

What updates what

Limits worth knowing

• A custom dataset created from chat is a snapshot. It has no bound source, so its figures stay as they were given until someone edits the dataset. It has no Refresh from source and no cadence.
• Cadence needs approval and an external trigger. Saving a cadence alone runs nothing. Approved upkeep has a finite allowance and only reviews the exact narrative scope you approved.
• Very large datasets. A dataset is stored as a single artifact, so a very large one can reach the size limit for one artifact. A dataset created from chat holds up to 200 figures and four views.
• The interactive view uses saved figures. Its figures are written into the page whenever the views are updated, and it is only as current as that update. In the #688 / #871 candidate, automatic editor execution requires a configured isolated preview site, valid organization-owner authoring approval and a fresh admission check; this is not a production-activation claim. Approved-owner edits may update the preview automatically; other members can execute only the approved saved snapshot. Generated HTML has no inherited approval. Agent writes, fills/refreshes that change HTML and cadence changes on the HTML artifact invalidate approval; review the new source and explicitly approve it again. See HTML Code Preview for trust/non-confidentiality, restore, unknown-save and revocation limits. On phones, the editor uses the available screen width without extra side gutters; the HTML's own spacing is preserved. Reload preview restarts it; Stop pauses it until Resume preview or a fresh editor open, still subject to admission. If live preview is unavailable, the source and static preview remain available; use Retry preview after a startup failure. Upload inspection and the library's quick preview remain static.
• The readable view shows values, not statuses. Check the dataset, or the dataset table in the interactive view, to see whether a figure is provisional, an estimate, or stale.
• Site overviews count every imported page. A page removed from the site still counts until you delete its source: open it from Knowledge → Sources and choose Delete. A manual refresh re-reads at most 500 pages of the crawl, so on larger sites some pages keep their earlier figures. Approved scheduled upkeep uses the smaller pilot limit shown in Upkeep.

Related articles

• Creating Artifacts -- Artifact types, editing, versions, and citations
• Uploading Documents -- Connecting GitHub and importing issues
• Asking Questions with Chat -- Everything chat can do, including living artifacts

Still need help?

Email us at hello@turnkeygtm.com -- we read every message.