# Open Links Safely In Oysterun

Oysterun turns supported links in chat, previews, Mail, Markdown, and Website
content into safe navigation. This page helps you recognize what should happen
when you open a link, how desktop behavior differs from the Oysterun app, and
what to do when a link cannot be opened.

## Prerequisites

- You are signed in to Oysterun.
- You are looking at a chat message, Markdown preview, Mail message, Website
  page, or another Oysterun surface that shows a link.
- For a local file or folder link, the Host must still have access to that file
  or folder from the Session or Browser Root that produced the link.

Starting screen: any Oysterun page that displays a visible link in message or
document content.

## Starting Action

Click or tap the visible link label. Use the label shown in the message or
document; you do not need to copy the hidden target.

Checkpoint: the current page either opens the supported target, shows the local
path disclosure for a local file or folder, or leaves the link as unavailable
text when Oysterun cannot open it safely.

## Supported Link Results

| Link you open | Desktop browser result | Oysterun app result |
| --- | --- | --- |
| File preview link | Opens the File Preview page in a new browser tab or window. | Opens the File Preview page inside the app. |
| Folder link | Opens the Explorer page in a new browser tab or window. | Opens the Explorer page inside the app. |
| Website page under `/sites/...` | Opens the Website page directly in a new browser tab or window. | Opens the Website page in the app Browser surface. |
| Oysterun app route under `/app/...` | Opens the Oysterun route in a new browser tab or window. | Opens the route inside the current app view. |
| External website URL | Opens according to your browser or app external-link policy. | Opens according to your app external-link policy. |

Checkpoint: supported Oysterun links keep you in Oysterun-controlled pages. A
desktop browser may use a new tab or window; the Oysterun app keeps supported
internal targets inside app-owned views.

## Open A Local File Or Folder Link

Local file and folder links use a two-click disclosure so you can see the local
path before opening it.

1. Click the link once.
2. Check the revealed local path text.
3. Click the disclosed action only if the path is the file or folder you expect.

Checkpoint: after the first click, the local path is visible. After the second
activation, a file opens in File Preview or a folder opens in Explorer.

If the path is not what you expected, stop after the first click and do not
activate the handoff.

## Open A Website Page Link

Website links that point to Oysterun-hosted pages use `/sites/...`.

An unavailable or malformed Website route returns a friendly HTTP `404`
unavailable page, but Website error handling must not intercept an existing
local file URL.
Existing local files continue to open through File Preview or Explorer under
the local-link rules below.

1. Click the visible Website link.
2. On desktop, expect a direct Website page in a new tab or window.
3. In the Oysterun app, expect the app Browser surface to open the Website page.

Checkpoint: the opened page address or in-app view points to the intended
Website page, not to a raw local file path.

## Open An Oysterun App Route

Links beginning with `/app/...` stay within Oysterun's trusted app namespace.
They may point to current or future Oysterun screens.

1. Click the visible app-route link.
2. On desktop, expect the route to open in a new tab or window.
3. In the Oysterun app, expect the current app view to navigate to that route.

Checkpoint: the target remains an Oysterun route. Unknown Oysterun routes stay
inside the app router instead of being treated as local files.

## Labels And Escaped Characters

Oysterun uses the label written in Markdown or the clean label supplied by the
link source. Internal bridge labels are not meant to appear in normal link
text.

Checkpoint: labels should not show internal annotation names, escaped Markdown
file extensions, or stray escape marks. Ordinary backslashes that are not part
of a link should remain visible.

## When A Link Is Unavailable

Oysterun fails closed when it cannot confirm that a local or internal target is
safe to open. The link may stay as plain text, show an unavailable state, or
open only the safe Oysterun fallback.

Bounded recovery:

1. Recheck the message or document and confirm that the visible label is the
   link you intended to open.
2. For a local file or folder link, use the first-click disclosure and compare
   the revealed path with the expected project or Session folder.
3. If the file or folder moved, ask the sender to share a new link from the
   current location or open the folder from Explorer.
4. If an Oysterun app route does not exist yet, return to the previous page and
   use the nearest visible navigation item for that task.
5. If an external website does not open, copy the visible URL only when you
   trust the sender and destination.

Stop after these checks if the target is still unavailable. Do not paste a
local path into a browser address bar just to bypass the Oysterun handoff.