Bug: workspace tab documentation causes LLMs to use browser-view instead of entity-view; missing decision rules and related requirement #69

Summary

The workspace documentation given to LLMs causes predictable errors when adding tabs pointing to URLs. The LLM reaches for browser-view (which opens a raw WebView with no history, bookmarking, or entity semantics) instead of first creating an external entity and using entity-view. The docs also omit any mention of related (required to make entities show as sub-items per #62) and give no type-agnostic guidance for deciding which tab kind to use for a given entity type.

Observed failure

When asked to "add a closed issues tab", the LLM:

1. Added a browser-view tab with a hardcoded URL — structurally valid but semantically wrong (bypasses entity model, no display-name, not queryable).
2. Required a follow-up correction to create an external entity first and switch the tab to entity-view.

The open-issues tab in the same workspace was already an entity-view → external entity, but the LLM did not learn from it because workspace-schema.md presents browser-view as an equally valid first-class option with no guidance on when to prefer one over the other.

Affected documentation files

1. JsonEntities/documentation/workspace-schema.md

Problems:

• Lists browser-view and entity-view as peers with no decision rule.
• No mention that URL-bearing content should be an external entity so it participates in the entity model (queryable, displayable, relatable).
• No mention of the related relationship requirement (per Workspaces view: show related entities as collapsed sub-items #62) when adding entity tabs.
• Example entity names are not in the correct ["namespace", "name"] array-of-arrays format that matches the schema.

Fix: Add a "Choosing a tab kind" section:

## Choosing a tab kind

Use `entity-view` for ALL entity-backed content. This includes:
- Notes, agent sessions, git repositories, tasks, and any other entity type.
- External URLs: create an `external` entity with a `urls` map first, then
  point the tab at it with `entity-view`. Do NOT use `browser-view` for URLs
  you want to track or revisit — external entities are queryable, displayable,
  and can be marked related to the workspace.

Use `browser-view` ONLY for transient, one-off URLs that do not warrant their
own entity (e.g. a temporary debug URL you will not reuse).

When adding an entity-view tab, also create a `related` relationship between
the workspace and the target entity so it appears as a sub-item in the
workspaces view. See "Adding a tab to a workspace" in issue #62.

Also add a full worked example showing: create external entity → create related relationship → add entity-view tab, all in one workspaces_entity_update call.

2. JsonEntities/documentation/external-schema.md

Problems:

• Example uses a generic name under ["external-systems", ...] — does not show the canonical ["external", "<name>"] naming convention used by all existing external entities (github-phantom-workspaces, phantom-workspaces-github-issues).
• No mention that the "default" URL key is special: it is the URL the workspace tab will open.
• No mention that entity-types must include "entity" as well as "external".

Fix: Update the example to use the ["external", "<name>"] naming convention, add a note that "default" is the primary URL opened by the workspace tab, and fix entity-types to include "entity".

3. JsonEntities/documentation/entity-workspace-agent-tool-instruction-details.md

Problems:

• Contains no guidance on workspace tab management at all.
• An LLM reading only this file (as instructed) gets no decision rules for tab kinds, no mention of external entities, and no mention of the related requirement.

Fix: Add a "Adding tabs to a workspace" section that covers:

1. Always prefer entity-view over browser-view.
2. For URLs, create an external entity first (with ["external", "<name>"] naming and a "default" URL key), then use entity-view pointing to it.
3. Always create a related relationship between the workspace and the target entity in the same update.
4. The correct entity-types for an external entity is ["entity", "external"].

Root cause

The documentation describes the data model but gives no decision rules for LLM callers. Adding the three-step process (create entity if needed → create related → add entity-view tab) as an explicit, type-agnostic recipe — alongside a clear "never use browser-view for tracked content" rule — would prevent the class of error observed here.