---
name: istari-links
description: >
  Build correct Istari Digital web-app deep links — to a System, a Resource in a
  branch tree, a workflow-log entry, or a model anywhere. Use for "give me a link
  to X", "the link shows No File Selected", or embedding URLs in READMEs.
---

# istari-links

Canonical table: [Linking to the web app](/markdown-source/current/developers/linking-to-the-web-app.md).

```text
system:            https://<host>/systems/<system_id>
file in tree:      https://<host>/systems/<system_id>/<branch>/tree/m~<resource_id>?tab=file
pinned revision:   …/tree/m~<resource_id>?tab=file&rev=<revision_id>
workflow entry:    https://<host>/systems/<system_id>?tab=workflow-log&entry=<entry_id>
anywhere:          https://<host>/files/<resource_id>
```

## Rules

1. **Host:** web app origin = Registry or API host minus `fileservice[-v2].` or `api.`. Links on the fileservice host look plausible and fail.
2. **Id:** `m~…` and `/files/…` take the **Resource id** (`tracked.resource_id`), never `file_id`. Wrong family → tree loads, nothing selected.
3. **Branch:** tag name. On a new System that is `baseline`, not `main`. Read it back (`b.tag`, `is_baseline`).
4. **Revision:** query `rev=`, not a path segment. `~latest` in the path is meaningless.
5. **Tab:** `?tab=file` opens preview. Workflow links need `tab=workflow-log` and `entry=`.

Read Resource ids **from the branch after commit**, not from an upload return value. A second `resources.create` of the same filename is a new Resource; a link to it is not in the tree.

Use `"model"` when uploading anything people should open from the tree (`istari-models`).

```python
import re

def ui_host(service_url: str) -> str:
    return re.sub(r"^(https?://)(fileservice(-v\d+)?|api)\.", r"\1", service_url)
```

| Symptom                                    | Cause                                                                                     |
| ------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Nothing selected, Resource visible in tree | `"file"` type, `file_id` in the link, or an untracked duplicate — check branch membership |
| 404 / blank on a plausible URL             | built on the fileservice host                                                             |
| Revision in the URL does nothing           | revision was put in the path; use `?rev=`                                                 |