diff --git a/CHANGELOG.md b/CHANGELOG.md
index a6c21cda9..8c786cca1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@
 
 ### Added
 
+- every command that takes an issue, project, document, initiative, team, or cycle now also takes the URL you copied out of Linear — `linear issue view https://linear.app/acme/issue/ENG-123/some-title`, `linear project view <project url>`, `--project`, `--parent`, `--team` and the rest, since they all resolve through the same lookups. `issue view <url>` did not work at all before; project and document URLs happened to work through an undocumented server-side behavior in Linear's API, which the CLI no longer relies on. A URL pointing at the wrong kind of thing now says so ("that is an issue URL, not a project URL") instead of reporting the whole URL as a missing name, as does one from another workspace or a page that names nothing (`/settings`). Cycle URLs work in all three forms the app produces — `/team/ENG/cycle/5`, `/cycle/active` and `/cycle/upcoming` (the CLI's `next`) — and carry their team: `cycle view <url>` uses it, and a `--team` that names a different team is refused rather than used to look up that team's cycle with the same number. Commands whose identifiers have no URL at all — milestones, labels, templates, releases — say that plainly. A comment link carries only the first eight characters of the comment's ID, so it names its issue but cannot be used as a comment ID. `issue link <url>` is unchanged: a lone URL there is still the thing being linked
 - `project view` now shows what Linear's project page shows: the long-form overview body (`content`), milestones with their status and progress, resources (`externalLinks`), documents, attachments, related projects with their dependency direction, labels, members, initiatives, and Linear's own progress percentage. Only `description` — the 255-character summary — was rendered before, so a project whose body was written with `project create --content-file` displayed nothing of it. A project reference can now be a UUID, slug ID, or exact name everywhere, including with `--web`/`--app`, and long output pages like `issue view` does (`--no-pager` to disable). `--json` keeps the GraphQL field names and the `{ nodes, pageInfo }` shape of every connection
 - `project view` with no argument opens a searchable list of projects to pick from, scoped like `project list` — the configured team, or the whole workspace when no team is set. It only prompts when stdin and stdout are both terminals; piped, redirected, in CI, or with `--json` it says a project is required instead of hanging on a prompt nobody can answer
 - `issue archive <id>` archives an issue through Linear's `issueArchive` mutation, distinct from `issue delete`, which trashes it. It resolves identifiers like the other issue commands, prompts with the identifier and title unless `--confirm`/`-y` is passed, reports an already-archived issue instead of silently succeeding, and takes `--bulk`, `--bulk-file`, and `--bulk-stdin` like `issue delete` ([#285](https://github.com/schpet/linear-cli/pull/285); thanks @martin-piliar for the command and the report in [#284](https://github.com/schpet/linear-cli/issues/284))
diff --git a/README.md b/README.md
index ca3aeef80..8f9e7e3cf 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,7 @@ linear user list --json # machine-readable output
 
 ```bash
 linear project list    # list projects
+linear project view https://linear.app/acme/project/mobile-launch-272f50ef9250  # paste a URL from Linear
 linear project view    # pick from a searchable list of projects
 linear project view <projectId>   # overview, milestones, resources, documents, related projects
 linear project view "Mobile launch"   # a UUID, slug ID, or exact name all work
diff --git a/deno.json b/deno.json
index ec06322e4..a216ded0c 100644
--- a/deno.json
+++ b/deno.json
@@ -39,6 +39,7 @@
     "@std/path": "jsr:@std/path@^1.1.4",
     "@std/toml": "jsr:@std/toml@^1.0.11",
     "@types/mdast": "npm:@types/mdast@^4.0.4",
+    "fast-check": "npm:fast-check@^4.10.2",
     "mdast": "npm:@types/mdast@^4.0.4",
     "graphql": "npm:graphql@^16.13.2",
     "./__generated__/graphql": "./src/__codegen__/graphql.ts",
diff --git a/deno.lock b/deno.lock
index 32373caca..5179a1652 100644
--- a/deno.lock
+++ b/deno.lock
@@ -46,6 +46,7 @@
     "npm:@graphql-typed-document-node/core@^3.2.0": "3.2.0_graphql@16.13.2",
     "npm:@types/mdast@^4.0.4": "4.0.4",
     "npm:@types/node@*": "24.2.0",
+    "npm:fast-check@^4.10.2": "4.10.2",
     "npm:graphql-request@^7.4.0": "7.4.0_graphql@16.13.2",
     "npm:graphql@^16.13.2": "16.13.2",
     "npm:lefthook@^2.1.4": "2.1.4",
@@ -1408,6 +1409,12 @@
     "extend@3.0.2": {
       "integrity": "sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g=="
     },
+    "fast-check@4.10.2": {
+      "integrity": "sha512-iK2f+YrcmoeGqk6fA0ea2bptcu/itMIm4NfEozq6N25+aG6h7s5HZbB/k1aV7b5w5sFLMCbbtRUsTVR+BgC3xw==",
+      "dependencies": [
+        "pure-rand"
+      ]
+    },
     "fast-glob@3.3.3": {
       "integrity": "sha512-7MptL8U0cqcFdzIzwOTHoilX9x5BrNqye7Z/LuC7kCMRio1EMSyqRK3BEAUD7sXRq4iT4AzTVuZdhgQ2TCvYLg==",
       "dependencies": [
@@ -2286,6 +2293,9 @@
     "picomatch@2.3.2": {
       "integrity": "sha512-V7+vQEJ06Z+c5tSye8S+nHUfI51xoXIXjHQ99cQtKUkQqqO1kO/KCJUfZXuB47h/YBlDhah2H3hdUGXn8ie0oA=="
     },
+    "pure-rand@8.4.2": {
+      "integrity": "sha512-vvuOGgcuPJAirlHvuQw1TrOiw7ptaIXXmIbNuiNOY6lNGJJH49PQ1Kj4nd783nPdQhQdicgOjVI2yI/9BD6/Ng=="
+    },
     "queue-microtask@1.2.3": {
       "integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A=="
     },
@@ -2686,6 +2696,7 @@
       "npm:@graphql-codegen/cli@^6.2.1",
       "npm:@graphql-typed-document-node/core@^3.2.0",
       "npm:@types/mdast@^4.0.4",
+      "npm:fast-check@^4.10.2",
       "npm:graphql-request@^7.4.0",
       "npm:graphql@^16.13.2",
       "npm:lefthook@^2.1.4",
diff --git a/docs/usage.md b/docs/usage.md
index 8d2fdfc56..b4edd9c19 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -363,6 +363,19 @@ linear project update PROJECT-ID --initiative "Q4 Bets" --initiative "Platform"
 linear project list
 ```
 
+#### referring to things by URL
+
+Anywhere the CLI takes an issue, project, document, initiative, team, or cycle, you can paste the URL from Linear instead of its ID, slug, or name.
+
+```bash
+linear issue view https://linear.app/acme/issue/ENG-123/some-title
+linear project view https://linear.app/acme/project/mobile-launch-272f50ef9250
+linear issue query --project https://linear.app/acme/project/mobile-launch-272f50ef9250
+linear cycle view https://linear.app/acme/team/ENG/cycle/active
+```
+
+The scheme is optional, and query strings and title slugs are ignored. A URL for the wrong kind of thing, or from another workspace, is reported as such.
+
 #### view project details
 
 Shows the project's overview body, milestones, resources, documents, attachments, related projects, latest status update, issue counts, and details. A project is a UUID, slug ID, or exact name.
diff --git a/src/commands/cycle/cycle-view.ts b/src/commands/cycle/cycle-view.ts
index 0f2d9024e..ccff4bf2b 100644
--- a/src/commands/cycle/cycle-view.ts
+++ b/src/commands/cycle/cycle-view.ts
@@ -14,6 +14,7 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
 
 const GetCycleDetails = gql(`
   query GetCycleDetails($id: String!) {
@@ -66,7 +67,15 @@ export const viewCommand = new Command()
   .option("-j, --json", "Output as JSON")
   .action(async ({ team, json }, cycleRef) => {
     try {
-      const teamKey = team || getTeamKey()
+      // A pasted cycle URL names its team. With no --team, that is the team
+      // meant — not whichever one happens to be configured. An explicit --team
+      // still wins, and the lookup refuses it if it contradicts the URL.
+      const urlTeamKey = expectLinearUrlKind(
+        cycleRef,
+        "cycle",
+        "a cycle URL, number, or name",
+      )?.teamKey
+      const teamKey = team || urlTeamKey || getTeamKey()
       if (!teamKey) {
         throw new ValidationError(
           "Could not determine team key from directory name or team flag",
diff --git a/src/commands/document/attachment-target.ts b/src/commands/document/attachment-target.ts
index d930c0c44..85bc1d4ed 100644
--- a/src/commands/document/attachment-target.ts
+++ b/src/commands/document/attachment-target.ts
@@ -16,6 +16,7 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
 
 // A Linear document is attached to exactly one target. The API enforces
 // "exactly one of initiativeId, teamId, issueId, releaseId, cycleId or
@@ -120,7 +121,19 @@ const GetIssueForDocumentTarget = gql(/* GraphQL */ `
 
 async function resolveIssueId(input: string): Promise<string> {
   const client = getGraphQLClient()
-  const id = isLinearUuid(input) ? input : input.toUpperCase()
+  // `--issue` on document create/list/update comes through here rather than
+  // `getIssueIdentifier`, so a pasted issue URL has to be read here too —
+  // otherwise it is uppercased whole and sent to the API as an identifier.
+  const urlRef = expectLinearUrlKind(
+    input,
+    "issue",
+    "an issue URL, identifier like ENG-123, or UUID",
+  )
+  const id = urlRef != null
+    ? urlRef.identifier
+    : isLinearUuid(input)
+    ? input
+    : input.toUpperCase()
   try {
     const result = await client.request(GetIssueForDocumentTarget, { id })
     if (result.issue) {
diff --git a/src/commands/document/document-comment-add.ts b/src/commands/document/document-comment-add.ts
index de1cd8f2a..dd6b588b7 100644
--- a/src/commands/document/document-comment-add.ts
+++ b/src/commands/document/document-comment-add.ts
@@ -16,6 +16,7 @@ import {
   REPLY_TO_DESCRIPTION,
   resolveCommentBody,
 } from "../../utils/comments.ts"
+import { resolveDocumentReference } from "../../utils/linear.ts"
 
 // A document comment attaches to the document's content record, not to the
 // document itself, so look that id up first. `document(id:)` accepts a UUID or
@@ -39,10 +40,13 @@ export const commentAddCommand = new Command()
   .option("-b, --body <text:string>", COMMENT_BODY_DESCRIPTION)
   .option("--body-file <path:string>", COMMENT_BODY_FILE_DESCRIPTION)
   .option("-p, --parent, --reply-to <commentId:string>", REPLY_TO_DESCRIPTION)
-  .action(async (options, document) => {
+  .action(async (options, rawDocument) => {
     const { body, bodyFile, parent } = options
 
     try {
+      // Inside the try: resolution rejects a wrong-kind or cross-workspace URL,
+      // and those errors have to reach handleError like every other failure.
+      const document = resolveDocumentReference(rawDocument)
       const textBody = await resolveCommentBody({ body, bodyFile })
 
       const client = getGraphQLClient()
diff --git a/src/commands/document/document-comment-list.ts b/src/commands/document/document-comment-list.ts
index 56928182f..89f71ad83 100644
--- a/src/commands/document/document-comment-list.ts
+++ b/src/commands/document/document-comment-list.ts
@@ -10,6 +10,7 @@ import {
   collectCommentPages,
   renderCommentThreads,
 } from "../../utils/comments.ts"
+import { resolveDocumentReference } from "../../utils/linear.ts"
 
 // `document(id:)` accepts a UUID or a slug ID, so no resolver is needed.
 const GetDocumentComments = gql(`
@@ -34,10 +35,13 @@ export const commentListCommand = new Command()
   .description("List comments on a document (by ID or slug)")
   .arguments("<document:string>")
   .option("-j, --json", "Output as JSON")
-  .action(async (options, document) => {
+  .action(async (options, rawDocument) => {
     const { json } = options
 
     try {
+      // Inside the try: resolution rejects a wrong-kind or cross-workspace URL,
+      // and those errors have to reach handleError like every other failure.
+      const document = resolveDocumentReference(rawDocument)
       const client = getGraphQLClient()
       const comments = await collectCommentPages(async (after) => {
         const data = await translateNotFound(
diff --git a/src/commands/document/document-delete.ts b/src/commands/document/document-delete.ts
index e28b8e756..7bb1fadfb 100644
--- a/src/commands/document/document-delete.ts
+++ b/src/commands/document/document-delete.ts
@@ -15,6 +15,7 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { resolveDocumentReference } from "../../utils/linear.ts"
 
 interface DocumentDeleteResult extends BulkOperationResult {
   title?: string
@@ -71,7 +72,7 @@ export const deleteCommand = new Command()
 async function handleSingleDelete(
   // deno-lint-ignore no-explicit-any
   client: any,
-  documentId: string,
+  rawDocumentId: string,
   options: { yes?: boolean },
 ): Promise<void> {
   const { yes } = options
@@ -87,10 +88,11 @@ async function handleSingleDelete(
     }
   `)
 
+  const documentId = resolveDocumentReference(rawDocumentId)
   const documentDetails = await client.request(detailsQuery, { id: documentId })
 
   if (!documentDetails?.document) {
-    throw new NotFoundError("Document", documentId)
+    throw new NotFoundError("Document", rawDocumentId)
   }
 
   const document = documentDetails.document
@@ -189,11 +191,14 @@ async function handleBulkDelete(
       }
     `)
 
-    let documentUuid = docId
+    const resolvedDocId = resolveDocumentReference(docId)
+    let documentUuid = resolvedDocId
     let title = docId
 
     try {
-      const details = await client.request(detailsQuery, { id: docId })
+      const details = await client.request(detailsQuery, {
+        id: resolvedDocId,
+      })
       if (details?.document) {
         documentUuid = details.document.id
         title = details.document.title
diff --git a/src/commands/document/document-update.ts b/src/commands/document/document-update.ts
index 4d8a8d868..b175556cf 100644
--- a/src/commands/document/document-update.ts
+++ b/src/commands/document/document-update.ts
@@ -20,6 +20,7 @@ import {
   toDocumentTargetInput,
 } from "./attachment-target.ts"
 import { withMarkdownHint } from "../../utils/markdown-help.ts"
+import { resolveDocumentReference } from "../../utils/linear.ts"
 
 const GetDocumentForEdit = gql(`
   query GetDocumentForEdit($id: String!) {
@@ -233,9 +234,10 @@ export const updateCommand = new Command()
         edit,
         force,
       },
-      documentId,
+      rawDocumentId,
     ) => {
       try {
+        const documentId = resolveDocumentReference(rawDocumentId)
         const targetOptions: DocumentTargetOptions = {
           project,
           issue,
diff --git a/src/commands/document/document-view.ts b/src/commands/document/document-view.ts
index b5ab4551c..be1210f98 100644
--- a/src/commands/document/document-view.ts
+++ b/src/commands/document/document-view.ts
@@ -16,6 +16,7 @@ import {
   isNotFoundError,
   NotFoundError,
 } from "../../utils/errors.ts"
+import { resolveDocumentReference } from "../../utils/linear.ts"
 
 const GetDocument = gql(`
   query GetDocument($id: String!) {
@@ -174,13 +175,14 @@ export const viewCommand = new Command()
   .option("-w, --web", "Open document in browser")
   .option("--json", "Output full document as JSON")
   .option("--no-download", "Keep remote URLs instead of downloading files")
-  .action(async ({ raw, web, json, download }, id) => {
+  .action(async ({ raw, web, json, download }, rawId) => {
     const { Spinner } = await import("@std/cli/unstable-spinner")
     const showSpinner = shouldShowSpinner() && !raw && !json
     const spinner = showSpinner ? new Spinner() : null
-    spinner?.start()
 
     try {
+      const id = resolveDocumentReference(rawId)
+      spinner?.start()
       const client = getGraphQLClient()
       const result = json
         ? { document: await getDocumentWithAllComments(client, id) }
@@ -293,7 +295,7 @@ export const viewCommand = new Command()
       // Report through handleError like every other failure; throwing from
       // here would escape the action and print a stack trace instead.
       const reported = isClientError(error) && isNotFoundError(error)
-        ? new NotFoundError("Document", id)
+        ? new NotFoundError("Document", rawId)
         : error
       handleError(reported, "Failed to view document")
     }
diff --git a/src/commands/initiative-update/initiative-update-create.ts b/src/commands/initiative-update/initiative-update-create.ts
index 00a2c493f..e577118d6 100644
--- a/src/commands/initiative-update/initiative-update-create.ts
+++ b/src/commands/initiative-update/initiative-update-create.ts
@@ -12,6 +12,8 @@ import {
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { withMarkdownHint } from "../../utils/markdown-help.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 const HEALTH_VALUES = ["onTrack", "atRisk", "offTrack"] as const
 type HealthValue = (typeof HEALTH_VALUES)[number]
@@ -43,6 +45,19 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative-update/initiative-update-list.ts b/src/commands/initiative-update/initiative-update-list.ts
index 9233a9e30..df4e8471a 100644
--- a/src/commands/initiative-update/initiative-update-list.ts
+++ b/src/commands/initiative-update/initiative-update-list.ts
@@ -8,6 +8,8 @@ import {
 import { handleError, NotFoundError } from "../../utils/errors.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 /**
  * Resolve initiative ID from UUID, slug, or name
@@ -17,6 +19,19 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-add-project.ts b/src/commands/initiative/initiative-add-project.ts
index d72031cec..af77500e5 100644
--- a/src/commands/initiative/initiative-add-project.ts
+++ b/src/commands/initiative/initiative-add-project.ts
@@ -3,6 +3,11 @@ import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { CliError, handleError, NotFoundError } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import {
+  findInitiativeIdBySlug,
+  findProjectIdBySlug,
+} from "../../utils/linear.ts"
 
 const AddProjectToInitiative = gql(`
   mutation AddProjectToInitiative($input: InitiativeToProjectCreateInput!) {
@@ -20,6 +25,18 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<{ id: string; name: string } | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
@@ -99,6 +116,18 @@ async function resolveProjectId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<{ id: string; name: string } | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "project",
+    "a project URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findProjectIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another project could win.
+    idOrSlugOrName = fromUrl
+  }
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-archive.ts b/src/commands/initiative/initiative-archive.ts
index 3a893750b..737196ff6 100644
--- a/src/commands/initiative/initiative-archive.ts
+++ b/src/commands/initiative/initiative-archive.ts
@@ -16,6 +16,8 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 interface InitiativeArchiveResult extends BulkOperationResult {
   name: string
@@ -299,6 +301,19 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-delete.ts b/src/commands/initiative/initiative-delete.ts
index 9c3e24d88..c9a0222c0 100644
--- a/src/commands/initiative/initiative-delete.ts
+++ b/src/commands/initiative/initiative-delete.ts
@@ -16,6 +16,8 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 interface InitiativeDeleteResult extends BulkOperationResult {
   name: string
@@ -307,6 +309,21 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId, {
+      includeArchived: true,
+    })
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-remove-project.ts b/src/commands/initiative/initiative-remove-project.ts
index 72081c4b2..c582f1cae 100644
--- a/src/commands/initiative/initiative-remove-project.ts
+++ b/src/commands/initiative/initiative-remove-project.ts
@@ -9,6 +9,11 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import {
+  findInitiativeIdBySlug,
+  findProjectIdBySlug,
+} from "../../utils/linear.ts"
 
 const GetInitiativeToProjects = gql(`
   query GetInitiativeToProjects($first: Int) {
@@ -39,6 +44,18 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<{ id: string; name: string } | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
@@ -118,6 +135,18 @@ async function resolveProjectId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<{ id: string; name: string } | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "project",
+    "a project URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findProjectIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another project could win.
+    idOrSlugOrName = fromUrl
+  }
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-unarchive.ts b/src/commands/initiative/initiative-unarchive.ts
index 3250e92bf..b5e849422 100644
--- a/src/commands/initiative/initiative-unarchive.ts
+++ b/src/commands/initiative/initiative-unarchive.ts
@@ -9,6 +9,8 @@ import {
   NotFoundError,
   ValidationError,
 } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 export const unarchiveCommand = new Command()
   .name("unarchive")
@@ -124,6 +126,21 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId, {
+      includeArchived: true,
+    })
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-update.ts b/src/commands/initiative/initiative-update.ts
index dd156c7ed..e47a88072 100644
--- a/src/commands/initiative/initiative-update.ts
+++ b/src/commands/initiative/initiative-update.ts
@@ -2,9 +2,10 @@ import { Command } from "@cliffy/command"
 import { Input, Select } from "@cliffy/prompt"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
-import { lookupUserId } from "../../utils/linear.ts"
+import { findInitiativeIdBySlug, lookupUserId } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { CliError, handleError, NotFoundError } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
 
 // Initiative status options from Linear API
 const INITIATIVE_STATUSES = [
@@ -229,6 +230,19 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/initiative/initiative-view.ts b/src/commands/initiative/initiative-view.ts
index 9d44b0e82..5f713d801 100644
--- a/src/commands/initiative/initiative-view.ts
+++ b/src/commands/initiative/initiative-view.ts
@@ -6,6 +6,8 @@ import { getGraphQLClient } from "../../utils/graphql.ts"
 import { formatRelativeTime } from "../../utils/display.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError, NotFoundError } from "../../utils/errors.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
+import { findInitiativeIdBySlug } from "../../utils/linear.ts"
 
 const GetInitiativeDetails = gql(`
   query GetInitiativeDetails($id: String!) {
@@ -254,6 +256,19 @@ async function resolveInitiativeId(
   client: any,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/issue/issue-agent-session-view.ts b/src/commands/issue/issue-agent-session-view.ts
index db54e3dee..04cb7dc67 100644
--- a/src/commands/issue/issue-agent-session-view.ts
+++ b/src/commands/issue/issue-agent-session-view.ts
@@ -5,6 +5,7 @@ import { getGraphQLClient } from "../../utils/graphql.ts"
 import { formatRelativeTime } from "../../utils/display.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { handleError, NotFoundError } from "../../utils/errors.ts"
+import { rejectLinearUrl } from "../../utils/linear-url.ts"
 
 const GetAgentSessionDetails = gql(`
   query GetAgentSessionDetails($id: String!) {
@@ -79,6 +80,7 @@ export const agentSessionViewCommand = new Command()
   .option("-j, --json", "Output as JSON")
   .action(async ({ json }, sessionId) => {
     try {
+      rejectLinearUrl(sessionId, "an agent session ID")
       const { Spinner } = await import("@std/cli/unstable-spinner")
       const showSpinner = shouldShowSpinner() && !json
       const spinner = showSpinner ? new Spinner() : null
diff --git a/src/commands/issue/issue-comment-delete.ts b/src/commands/issue/issue-comment-delete.ts
index 4932fb68e..1711c6646 100644
--- a/src/commands/issue/issue-comment-delete.ts
+++ b/src/commands/issue/issue-comment-delete.ts
@@ -2,6 +2,7 @@ import { Command } from "@cliffy/command"
 import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { CliError, handleError } from "../../utils/errors.ts"
+import { rejectCommentUrl, rejectLinearUrl } from "../../utils/linear-url.ts"
 
 export const commentDeleteCommand = new Command()
   .name("delete")
@@ -9,6 +10,8 @@ export const commentDeleteCommand = new Command()
   .arguments("<commentId:string>")
   .action(async (_options, commentId) => {
     try {
+      rejectCommentUrl(commentId)
+      rejectLinearUrl(commentId, "a comment UUID")
       const mutation = gql(`
         mutation DeleteComment($id: String!) {
           commentDelete(id: $id) {
diff --git a/src/commands/issue/issue-comment-update.ts b/src/commands/issue/issue-comment-update.ts
index d4779a5d3..334a4ed6d 100644
--- a/src/commands/issue/issue-comment-update.ts
+++ b/src/commands/issue/issue-comment-update.ts
@@ -4,6 +4,7 @@ import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
 import { withMarkdownHint } from "../../utils/markdown-help.ts"
+import { rejectCommentUrl, rejectLinearUrl } from "../../utils/linear-url.ts"
 
 export const commentUpdateCommand = new Command()
   .name("update")
@@ -18,6 +19,8 @@ export const commentUpdateCommand = new Command()
     const { body, bodyFile } = options
 
     try {
+      rejectCommentUrl(commentId)
+      rejectLinearUrl(commentId, "a comment UUID")
       // Validate that body and bodyFile are not both provided
       if (body && bodyFile) {
         throw new ValidationError(
diff --git a/src/commands/label/label-delete.ts b/src/commands/label/label-delete.ts
index 25a9174bb..c2c6abc76 100644
--- a/src/commands/label/label-delete.ts
+++ b/src/commands/label/label-delete.ts
@@ -4,6 +4,7 @@ import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { getTeamKey, resolveTeam } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
+import { rejectLinearUrl } from "../../utils/linear-url.ts"
 import {
   CliError,
   handleError,
@@ -66,6 +67,7 @@ async function resolveLabelId(
   nameOrId: string,
   teamKey?: string,
 ): Promise<Label | undefined> {
+  rejectLinearUrl(nameOrId, "a label name or UUID")
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/commands/milestone/milestone-delete.ts b/src/commands/milestone/milestone-delete.ts
index 585dc40e3..8ed67437d 100644
--- a/src/commands/milestone/milestone-delete.ts
+++ b/src/commands/milestone/milestone-delete.ts
@@ -4,6 +4,7 @@ import { gql } from "../../__codegen__/gql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
+import { rejectLinearUrl } from "../../utils/linear-url.ts"
 
 const DeleteProjectMilestone = gql(`
   mutation DeleteProjectMilestone($id: String!) {
@@ -19,6 +20,14 @@ export const deleteCommand = new Command()
   .arguments("<id:string>")
   .option("-f, --force", "Skip confirmation prompt")
   .action(async ({ force }, id) => {
+    // Milestones have no URL of their own. Refused before the confirmation
+    // prompt, so nobody is asked to confirm deleting a URL.
+    try {
+      rejectLinearUrl(id, "a milestone UUID")
+    } catch (error) {
+      handleError(error, "Failed to delete milestone")
+    }
+
     // Confirmation prompt unless --force is used
     if (!force) {
       if (!Deno.stdin.isTerminal()) {
diff --git a/src/commands/milestone/milestone-update.ts b/src/commands/milestone/milestone-update.ts
index fe93e13ab..09f2ff52e 100644
--- a/src/commands/milestone/milestone-update.ts
+++ b/src/commands/milestone/milestone-update.ts
@@ -4,6 +4,7 @@ import { getGraphQLClient } from "../../utils/graphql.ts"
 import { resolveProjectId } from "../../utils/linear.ts"
 import { shouldShowSpinner } from "../../utils/hyperlink.ts"
 import { CliError, handleError, ValidationError } from "../../utils/errors.ts"
+import { rejectLinearUrl } from "../../utils/linear-url.ts"
 
 const UpdateProjectMilestone = gql(`
   mutation UpdateProjectMilestone($id: String!, $input: ProjectMilestoneUpdateInput!) {
@@ -43,6 +44,12 @@ export const updateCommand = new Command()
       { name, description, targetDate, sortOrder, project: projectIdOrSlug },
       id,
     ) => {
+      try {
+        rejectLinearUrl(id, "a milestone UUID")
+      } catch (error) {
+        handleError(error, "Failed to update milestone")
+      }
+
       if (
         !name && !description && !targetDate && sortOrder == null &&
         !projectIdOrSlug
diff --git a/src/commands/project/project-create.ts b/src/commands/project/project-create.ts
index 8ed792666..1343ebd43 100644
--- a/src/commands/project/project-create.ts
+++ b/src/commands/project/project-create.ts
@@ -5,6 +5,7 @@ import type { ProjectCreateInput } from "../../__codegen__/graphql.ts"
 import { getGraphQLClient } from "../../utils/graphql.ts"
 import type { GraphQLClient } from "graphql-request"
 import {
+  findInitiativeIdBySlug,
   getAllTeams,
   getProjectLabelIdByName,
   getTeamKey,
@@ -24,6 +25,7 @@ import {
 } from "./project-description.ts"
 import { withMarkdownHint } from "../../utils/markdown-help.ts"
 import { resolveTemplate } from "../../utils/templates.ts"
+import { expectLinearUrlKind } from "../../utils/linear-url.ts"
 
 const CreateProject = gql(`
   mutation CreateProject($input: ProjectCreateInput!) {
@@ -81,6 +83,19 @@ async function resolveInitiativeId(
   client: GraphQLClient,
   idOrSlugOrName: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    idOrSlugOrName,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) return undefined
+    // Now a UUID, so the UUID branch below takes it and a URL never
+    // falls through to a name lookup another initiative could win.
+    idOrSlugOrName = fromUrl
+  }
+
   // Try as UUID first
   if (
     /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
diff --git a/src/utils/comments.ts b/src/utils/comments.ts
index d58da1e85..f0c94a066 100644
--- a/src/utils/comments.ts
+++ b/src/utils/comments.ts
@@ -14,6 +14,7 @@ import type {
 import { getGraphQLClient } from "./graphql.ts"
 import { formatRelativeTime } from "./display.ts"
 import { CliError, ValidationError } from "./errors.ts"
+import { rejectCommentUrl, rejectLinearUrl } from "./linear-url.ts"
 
 /** Shared option descriptions so the four `comment add` commands read alike. */
 export const COMMENT_BODY_DESCRIPTION = "Comment body text"
@@ -48,6 +49,11 @@ export function buildCommentCreateInput(
 ): CommentCreateInput {
   const input: CommentCreateInput = { body: options.body }
   if (options.parentId != null) {
+    // Every comment-add command's --reply-to lands here. A pasted comment link
+    // carries only the first eight characters of the comment's ID, so it gets
+    // the specific explanation; any other Linear URL gets the general one.
+    rejectCommentUrl(options.parentId)
+    rejectLinearUrl(options.parentId, "the UUID of the comment to reply to")
     input.parentId = options.parentId
   }
   if (options.id != null) {
diff --git a/src/utils/linear-url.ts b/src/utils/linear-url.ts
new file mode 100644
index 000000000..5c4635d02
--- /dev/null
+++ b/src/utils/linear-url.ts
@@ -0,0 +1,464 @@
+import { getCliWorkspace, getOption } from "../config.ts"
+import { getDefaultWorkspace } from "../credentials.ts"
+import { normalizeIssueIdentifier } from "./issue-identifier.ts"
+import { ValidationError } from "./errors.ts"
+
+/** Linear serves its app from this host only; it offers no custom domains. */
+const LINEAR_APP_HOSTS: readonly string[] = ["linear.app", "www.linear.app"]
+
+/**
+ * Project, document and initiative URLs all end in `{name-slug}-{slugId}`,
+ * where the slug ID is twelve hex characters. The name part is decorative.
+ */
+const SLUG_ID_RE = /^[0-9a-f]{12}$/
+
+/** Comment and project-update anchors carry the first eight characters of a UUID. */
+const COMMENT_ANCHOR_RE = /^comment-([0-9a-f]{8})$/
+const PROJECT_UPDATE_ANCHOR_RE = /^project-update-[0-9a-f]{8}$/
+
+/**
+ * Team pages that still mean "this team". Linear puts other entities under
+ * `/team/{KEY}/` too — a cycle lives at `/team/{KEY}/cycle/5` — so an unknown
+ * descendant is refused rather than assumed to denote the team; `team delete`
+ * reads this.
+ *
+ * `overview` (the team's home), `all`, `active`, `cycles`, `projects/all` and
+ * `views/issues` are the pages the app's sidebar and tabs actually produce.
+ * The rest are expected but unobserved; an entry for a page that does not
+ * exist is harmless, since it can only fail to match.
+ */
+const TEAM_SUBPAGES: readonly string[] = [
+  "overview",
+  "all",
+  "active",
+  "backlog",
+  "triage",
+  "cycles",
+  "projects",
+  "projects/all",
+  "views/issues",
+  "settings",
+]
+
+/** Pages under a project that still mean the project. */
+const PROJECT_SUBPAGES: readonly string[] = [
+  "overview",
+  "issues",
+  "updates",
+  "activity",
+]
+
+/**
+ * The app addresses a cycle by its number, or relatively. Its `upcoming` is
+ * the cycle the CLI already calls `next`. No other relative form was observed,
+ * so no other is accepted.
+ */
+const CYCLE_ALIASES: Record<string, "active" | "next"> = {
+  active: "active",
+  upcoming: "next",
+}
+
+export type LinearUrlRef =
+  | {
+    kind: "issue"
+    workspace: string
+    identifier: string
+    /**
+     * Set when the URL pointed at a specific comment. Only the first eight
+     * characters of the comment's UUID survive in the anchor, so this is
+     * enough to explain the problem to the user but not to identify a comment.
+     */
+    commentIdPrefix?: string
+  }
+  | { kind: "project"; workspace: string; slugId: string }
+  | { kind: "document"; workspace: string; slugId: string }
+  | { kind: "initiative"; workspace: string; slugId: string }
+  | { kind: "team"; workspace: string; teamKey: string }
+  | {
+    kind: "cycle"
+    workspace: string
+    teamKey: string
+    /** A cycle number, or the relative cycle the URL names. */
+    cycle: number | "active" | "next"
+  }
+
+export type LinearUrlParse =
+  /** Ordinary input. Callers fall through to their existing lookup unchanged. */
+  | { status: "not-linear-url" }
+  /**
+   * Recognisably a Linear URL, but not one that names something the CLI can
+   * look up. Callers must report this rather than retrying it as a name — a
+   * settings URL looked up as a project name is exactly the confusing
+   * "not found: https://…" this module exists to remove.
+   */
+  | { status: "unsupported"; reason: string }
+  | { status: "ok"; ref: LinearUrlRef }
+
+const ENTITY_LABELS: Record<LinearUrlRef["kind"], string> = {
+  issue: "an issue",
+  project: "a project",
+  document: "a document",
+  initiative: "an initiative",
+  team: "a team",
+  cycle: "a cycle",
+}
+
+function unsupported(reason: string): LinearUrlParse {
+  return { status: "unsupported", reason }
+}
+
+/**
+ * Pull the twelve-hex slug ID off a `{name-slug}-{slugId}` path segment.
+ *
+ * A project can be named so that its slug is the whole segment, so a segment
+ * that is itself a bare slug ID is accepted as-is. Anything else fails loudly
+ * instead of sending a decorative slug to the API.
+ */
+function extractSlugId(segment: string): string | undefined {
+  const lower = segment.toLowerCase()
+  if (SLUG_ID_RE.test(lower)) {
+    return lower
+  }
+  const lastDash = lower.lastIndexOf("-")
+  if (lastDash === -1) {
+    return undefined
+  }
+  const candidate = lower.slice(lastDash + 1)
+  return SLUG_ID_RE.test(candidate) ? candidate : undefined
+}
+
+function toUrl(value: string): URL | undefined {
+  const trimmed = value.trim()
+  if (trimmed === "") {
+    return undefined
+  }
+
+  // People paste `linear.app/...` without a scheme. Only add one for a host we
+  // would accept anyway, so an ordinary name is never mistaken for a URL.
+  const withScheme = /^https?:\/\//i.test(trimmed)
+    ? trimmed
+    : LINEAR_APP_HOSTS.some((host) =>
+        trimmed.toLowerCase().startsWith(`${host}/`)
+      )
+    ? `https://${trimmed}`
+    : trimmed
+
+  try {
+    return new URL(withScheme)
+  } catch {
+    return undefined
+  }
+}
+
+function parseCyclePath(
+  workspace: string,
+  teamKey: string,
+  rest: readonly string[],
+): LinearUrlParse {
+  const [segment, ...extra] = rest
+  if (segment == null) {
+    return unsupported("it does not name a cycle")
+  }
+  if (extra.length > 0) {
+    return unsupported(`"${rest.join("/")}" is not a cycle page`)
+  }
+
+  const alias = CYCLE_ALIASES[segment.toLowerCase()]
+  if (alias != null) {
+    return {
+      status: "ok",
+      ref: {
+        kind: "cycle",
+        workspace,
+        teamKey: teamKey.toUpperCase(),
+        cycle: alias,
+      },
+    }
+  }
+
+  if (/^[1-9][0-9]*$/.test(segment)) {
+    const cycle = Number(segment)
+    if (Number.isSafeInteger(cycle)) {
+      return {
+        status: "ok",
+        ref: {
+          kind: "cycle",
+          workspace,
+          teamKey: teamKey.toUpperCase(),
+          cycle,
+        },
+      }
+    }
+  }
+
+  return unsupported(`"${segment}" is not a cycle number`)
+}
+
+/**
+ * Classify a user-supplied reference.
+ *
+ * The URL is only ever read, never fetched, so `http` is accepted alongside
+ * `https`. A port, embedded credentials, a subdomain or a lookalike host
+ * (`linear.app.example.com`) all mean this is not a Linear URL.
+ */
+export function parseLinearUrl(value: string): LinearUrlParse {
+  const url = toUrl(value)
+  if (url == null) {
+    return { status: "not-linear-url" }
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    return { status: "not-linear-url" }
+  }
+  const hostname = url.hostname.toLowerCase().replace(/\.$/, "")
+  if (!LINEAR_APP_HOSTS.includes(hostname)) {
+    return { status: "not-linear-url" }
+  }
+  if (url.port !== "" || url.username !== "" || url.password !== "") {
+    return { status: "not-linear-url" }
+  }
+
+  let segments: string[]
+  try {
+    segments = url.pathname
+      .split("/")
+      .filter((segment) => segment !== "")
+      .map((segment) => decodeURIComponent(segment))
+  } catch {
+    return unsupported("its path could not be decoded")
+  }
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return unsupported("its path contains relative segments")
+  }
+
+  const [workspace, entity, ...rest] = segments
+  if (workspace == null || entity == null) {
+    return unsupported("it does not name a workspace and an entity")
+  }
+
+  const anchor = url.hash.startsWith("#") ? url.hash.slice(1) : ""
+
+  switch (entity) {
+    case "issue": {
+      const raw = rest[0]
+      if (raw == null) {
+        return unsupported("it does not name an issue")
+      }
+      const identifier = normalizeIssueIdentifier(raw)
+      if (identifier == null) {
+        return unsupported(`"${raw}" is not an issue identifier`)
+      }
+      if (anchor === "") {
+        return { status: "ok", ref: { kind: "issue", workspace, identifier } }
+      }
+      const comment = anchor.match(COMMENT_ANCHOR_RE)
+      if (comment?.[1] != null) {
+        return {
+          status: "ok",
+          ref: {
+            kind: "issue",
+            workspace,
+            identifier,
+            commentIdPrefix: comment[1],
+          },
+        }
+      }
+      // An anchor we cannot read might mean something we would be ignoring.
+      return unsupported(`"#${anchor}" is not a comment link`)
+    }
+
+    case "project":
+    case "document":
+    case "initiative": {
+      const raw = rest[0]
+      if (raw == null) {
+        return unsupported(`it does not name ${ENTITY_LABELS[entity]}`)
+      }
+      const slugId = extractSlugId(raw)
+      if (slugId == null) {
+        return unsupported(`"${raw}" does not end in a Linear slug ID`)
+      }
+      const tail = rest.slice(1).join("/")
+      // A project's tabs all mean the project: its overview, issues, updates,
+      // and `/activity`, where status updates live (the update anchor names one
+      // update, which nothing in the CLI addresses by ID). Anything else under
+      // a project is refused rather than assumed to be the project.
+      if (
+        tail !== "" &&
+        !(entity === "project" && PROJECT_SUBPAGES.includes(tail))
+      ) {
+        return unsupported(`"${tail}" is not a page this command can use`)
+      }
+      if (
+        anchor !== "" && !PROJECT_UPDATE_ANCHOR_RE.test(anchor)
+      ) {
+        return unsupported(`"#${anchor}" is not a link this command can use`)
+      }
+      return { status: "ok", ref: { kind: entity, workspace, slugId } }
+    }
+
+    case "team": {
+      const teamKey = rest[0]
+      if (teamKey == null) {
+        return unsupported("it does not name a team")
+      }
+      const tail = rest.slice(1).join("/")
+      if (rest[1] === "cycle") {
+        return parseCyclePath(workspace, teamKey, rest.slice(2))
+      }
+      if (tail !== "" && !TEAM_SUBPAGES.includes(tail)) {
+        return unsupported(`"${tail}" is not a team page this command can use`)
+      }
+      return {
+        status: "ok",
+        ref: { kind: "team", workspace, teamKey: teamKey.toUpperCase() },
+      }
+    }
+
+    default:
+      return unsupported(`"${entity}" is not an entity this command can use`)
+  }
+}
+
+/**
+ * The workspace this invocation is working in, as far as can be told without a
+ * request: the `--workspace` flag, then the configured workspace, then the
+ * default credential.
+ *
+ * Under a raw `LINEAR_API_KEY` the key's organization is not knowable locally,
+ * so the configured slug is a declaration rather than proof. Trusting it anyway
+ * is deliberate and matches what the CLI already does elsewhere —
+ * `openProjectPage` builds the URLs a user opens out of this same option. The
+ * alternative, staying silent whenever a raw key is in play, would disable the
+ * check for the most common setup, which is exactly when someone pastes a URL
+ * from the wrong workspace. A false positive costs one clear, self-explanatory
+ * error naming both workspaces.
+ */
+function getEffectiveWorkspaceSlug(): string | undefined {
+  const configured = getCliWorkspace() ?? getOption("workspace") ??
+    getDefaultWorkspace()
+  const trimmed = configured?.trim()
+  return trimmed == null || trimmed === "" ? undefined : trimmed
+}
+
+function assertSameWorkspace(urlWorkspace: string): void {
+  const current = getEffectiveWorkspaceSlug()
+  if (current == null) {
+    return
+  }
+  if (current.toLowerCase() === urlWorkspace.toLowerCase()) {
+    return
+  }
+  throw new ValidationError(
+    `That URL is for the "${urlWorkspace}" workspace, but this is the "${current}" workspace.`,
+    { suggestion: switchWorkspaceSuggestion(urlWorkspace, current) },
+  )
+}
+
+/**
+ * How to reach another workspace depends on where the API key comes from,
+ * mirroring the precedence in `getResolvedApiKey`. Suggesting --workspace to
+ * someone whose key comes from LINEAR_API_KEY would send them straight into a
+ * second error — the CLI refuses that combination — and a config `api_key`
+ * outranks --workspace, so there the flag would silently change nothing.
+ */
+function switchWorkspaceSuggestion(
+  urlWorkspace: string,
+  current: string,
+): string {
+  const fromUrl = `or use a URL from "${current}".`
+  if (Deno.env.get("LINEAR_API_KEY") != null) {
+    return `LINEAR_API_KEY is set, and the CLI won't combine it with --workspace. Unset it and pass --workspace ${urlWorkspace}, ${fromUrl}`
+  }
+  if (getOption("api_key") != null) {
+    return `The api_key in your config outranks --workspace. Remove it to pass --workspace ${urlWorkspace}, ${fromUrl}`
+  }
+  return `Pass --workspace ${urlWorkspace}, ${fromUrl}`
+}
+
+/**
+ * Extract a reference of the expected kind from a URL.
+ *
+ * Returns `undefined` when the input is not a Linear URL at all, so callers keep
+ * their existing UUID / slug / name handling for ordinary input. Throws when the
+ * input is a Linear URL that names something else, names nothing usable, or
+ * belongs to another workspace.
+ */
+/**
+ * TypeScript cannot narrow a union by comparing against a generic kind, so the
+ * relationship is stated once here as a type predicate rather than asserted
+ * with a cast at the call site.
+ */
+function isRefOfKind<K extends LinearUrlRef["kind"]>(
+  ref: LinearUrlRef,
+  kind: K,
+): ref is Extract<LinearUrlRef, { kind: K }> {
+  return ref.kind === kind
+}
+
+export function expectLinearUrlKind<K extends LinearUrlRef["kind"]>(
+  input: string,
+  kind: K,
+  entityLabel: string,
+): Extract<LinearUrlRef, { kind: K }> | undefined {
+  const parsed = parseLinearUrl(input)
+  if (parsed.status === "not-linear-url") {
+    return undefined
+  }
+  if (parsed.status === "unsupported") {
+    throw new ValidationError(
+      `"${input}" is a Linear URL, but ${parsed.reason}.`,
+      { suggestion: `Pass ${entityLabel}.` },
+    )
+  }
+
+  const { ref } = parsed
+  assertSameWorkspace(ref.workspace)
+
+  if (!isRefOfKind(ref, kind)) {
+    throw new ValidationError(
+      `"${input}" is ${ENTITY_LABELS[ref.kind]} URL, not ${
+        ENTITY_LABELS[kind]
+      } URL.`,
+      { suggestion: `Pass ${entityLabel}.` },
+    )
+  }
+
+  return ref
+}
+
+/**
+ * For commands whose identifiers have no Linear URL at all (milestones, labels,
+ * templates, releases, agent sessions). A pasted URL is reported plainly
+ * instead of becoming a lookup for a string starting with `https://`.
+ */
+export function rejectLinearUrl(input: string, entityLabel: string): void {
+  const parsed = parseLinearUrl(input)
+  if (parsed.status === "not-linear-url") {
+    return
+  }
+  throw new ValidationError(
+    `"${input}" is a Linear URL, and this command does not take one.`,
+    { suggestion: `Pass ${entityLabel}.` },
+  )
+}
+
+/**
+ * A comment URL keeps only the first eight characters of the comment's UUID, so
+ * it cannot identify a comment. Commands that act on a comment say so directly
+ * rather than looking up something they cannot pin down.
+ */
+export function rejectCommentUrl(input: string): void {
+  const parsed = parseLinearUrl(input)
+  if (parsed.status !== "ok") {
+    return
+  }
+  if (parsed.ref.kind === "issue" && parsed.ref.commentIdPrefix != null) {
+    throw new ValidationError(
+      `"${input}" links to a comment, but a comment URL only carries the first eight characters of its ID.`,
+      {
+        suggestion:
+          "Pass the comment's full UUID, from `linear issue comment list <issue> --json`.",
+      },
+    )
+  }
+}
diff --git a/src/utils/linear.ts b/src/utils/linear.ts
index 70f378667..d698d490a 100644
--- a/src/utils/linear.ts
+++ b/src/utils/linear.ts
@@ -25,6 +25,7 @@ import {
 import { CliError, NotFoundError, ValidationError } from "./errors.ts"
 import { getGraphQLClient } from "./graphql.ts"
 import { normalizeIssueIdentifier } from "./issue-identifier.ts"
+import { expectLinearUrlKind, rejectLinearUrl } from "./linear-url.ts"
 import { getCurrentIssueFromVcs } from "./vcs.ts"
 
 /**
@@ -102,6 +103,18 @@ export async function getIssueIdentifier(
   providedId?: string,
 ): Promise<string | undefined> {
   if (providedId) {
+    // A pasted issue URL carries the identifier in its path. Reading it here
+    // covers every command and flag that funnels through this function,
+    // including --parent and both sides of `issue relation`.
+    const urlRef = expectLinearUrlKind(
+      providedId,
+      "issue",
+      "an issue URL or an identifier like ENG-123",
+    )
+    if (urlRef != null) {
+      return urlRef.identifier
+    }
+
     const normalizedIdentifier = normalizeIssueIdentifier(providedId)
     if (normalizedIdentifier) {
       return normalizedIdentifier
@@ -319,6 +332,9 @@ export function resolveWorkflowState(
   states: readonly WorkflowState[],
   nameOrType: string,
 ): WorkflowState | undefined {
+  // Workflow states have no URL; a pasted one is refused here rather than
+  // reported as a state that does not exist.
+  rejectLinearUrl(nameOrType, "a workflow state name or type")
   const nameMatch = states.find(
     (s) => s.name.toLowerCase() === nameOrType.toLowerCase(),
   )
@@ -455,6 +471,7 @@ export async function resolveStateSelection(
   const types: string[] = []
   const lookups: string[] = []
   for (const value of values) {
+    rejectLinearUrl(value, "a workflow state name, type, or ID")
     if (value.trim() === "") {
       throw new ValidationError("--state value is empty", {
         suggestion: `Pass a state type (${
@@ -1616,14 +1633,64 @@ export function isLinearUuid(value: string): boolean {
   return UUID_REGEX.test(value)
 }
 
+/**
+ * Normalise a document reference.
+ *
+ * `document(id:)` already accepts a UUID or a slug ID, so a pasted document URL
+ * only has to be reduced to its slug ID. Anything that is not a Linear URL is
+ * handed back untouched.
+ */
+export function resolveDocumentReference(input: string): string {
+  const urlRef = expectLinearUrlKind(
+    input,
+    "document",
+    "a document URL, UUID, or slug ID",
+  )
+  return urlRef?.slugId ?? input
+}
+
 /**
  * Look up a project ID by UUID, slug ID, or exact name.
  * Returns undefined when no project matches. Use [[resolveProjectId]] when
  * you want a missing project to throw.
  */
+/**
+ * Look up a project by slug ID and nothing else.
+ *
+ * A reference taken from a URL must come through here rather than the general
+ * lookup: a twelve-hex slug ID is also a perfectly legal project *name*, and
+ * `getProjectIdByName` tries names first, so a project named after another
+ * project's slug would win — and `project delete <url>` would delete it.
+ */
+export async function findProjectIdBySlug(
+  slugId: string,
+): Promise<string | undefined> {
+  const client = getGraphQLClient()
+  const slugQuery = gql(/* GraphQL */ `
+    query GetProjectIdBySlugId($slugId: String!) {
+      projects(filter: { slugId: { eq: $slugId } }) {
+        nodes {
+          id
+        }
+      }
+    }
+  `)
+  const slugData = await client.request(slugQuery, { slugId })
+  return slugData.projects?.nodes[0]?.id
+}
+
 export async function getProjectIdByName(
   input: string,
 ): Promise<string | undefined> {
+  const urlRef = expectLinearUrlKind(
+    input,
+    "project",
+    "a project URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    return await findProjectIdBySlug(urlRef.slugId)
+  }
+
   if (isLinearUuid(input)) return input
 
   const client = getGraphQLClient()
@@ -1655,17 +1722,7 @@ export async function getProjectIdByName(
   const nameMatch = nameMatches[0]?.id
   if (nameMatch) return nameMatch
 
-  const slugQuery = gql(/* GraphQL */ `
-    query GetProjectIdBySlugId($slugId: String!) {
-      projects(filter: { slugId: { eq: $slugId } }) {
-        nodes {
-          id
-        }
-      }
-    }
-  `)
-  const slugData = await client.request(slugQuery, { slugId: input })
-  return slugData.projects?.nodes[0]?.id
+  return await findProjectIdBySlug(input)
 }
 
 /**
@@ -1771,6 +1828,14 @@ export async function findTeam(
       suggestion: "Pass a team key, name, or ID, e.g. --team ENG.",
     })
   }
+  const urlRef = expectLinearUrlKind(
+    reference,
+    "team",
+    "a team URL, key, name, or ID",
+  )
+  if (urlRef != null) {
+    reference = urlRef.teamKey
+  }
   const client = getGraphQLClient()
   const query = gql(/* GraphQL */ `
     query ResolveTeam($reference: String!, $id: ID, $isUuid: Boolean!) {
@@ -1921,6 +1986,9 @@ export async function lookupUserId(
    */
   input: "self" | "@me" | string,
 ): Promise<string | undefined> {
+  // A profile URL is not one of the common things the CLI accepts a URL for,
+  // so it is refused plainly rather than searched for as a username.
+  rejectLinearUrl(input, "an email, username, display name, or @me")
   if (input === "@me" || input === "self") {
     const client = getGraphQLClient()
     const query = gql(/* GraphQL */ `
@@ -1980,6 +2048,9 @@ export async function getIssueLabelIdByNameForTeam(
   name: string,
   teamKey: string,
 ): Promise<string | undefined> {
+  // Labels have no URL of their own, so a pasted one is refused here rather
+  // than looked up as a label name and reported missing.
+  rejectLinearUrl(name, "a label name")
   const client = getGraphQLClient()
   const query = gql(/* GraphQL */ `
     query GetIssueLabelIdByNameForTeam($name: String!, $teamKey: String!) {
@@ -2003,6 +2074,7 @@ export async function getIssueLabelIdByNameForTeam(
 export async function getProjectLabelIdByName(
   name: string,
 ): Promise<string | undefined> {
+  rejectLinearUrl(name, "a project label name")
   const client = getGraphQLClient()
   const query = gql(/* GraphQL */ `
     query GetProjectLabelIdByName($name: String!) {
@@ -2324,6 +2396,9 @@ export async function resolveMilestoneId(
   input: string,
   projectId?: string,
 ): Promise<string> {
+  // Linear has no milestone URL, so a pasted URL here is always a mistake and
+  // is said so plainly rather than looked up as a milestone name.
+  rejectLinearUrl(input, "a milestone name or UUID")
   if (isLinearUuid(input)) return input
   if (!projectId) {
     throw new ValidationError(
@@ -2372,6 +2447,11 @@ export async function getCycleIdByNameOrNumber(
   cycleNameOrNumber: string,
   teamId: string,
 ): Promise<string> {
+  const urlRef = expectLinearUrlKind(
+    cycleNameOrNumber,
+    "cycle",
+    "a cycle URL, number, or name",
+  )
   const client = getGraphQLClient()
   const query = gql(/* GraphQL */ `
     query GetTeamCyclesForLookup($teamId: String!, $after: String) {
@@ -2404,6 +2484,20 @@ export async function getCycleIdByNameOrNumber(
   if (!data.team) {
     throw new NotFoundError("Team", teamId)
   }
+  // Checked before anything about the team's cycles: when a cycle URL names a
+  // different team, that contradiction is the problem worth reporting, not
+  // whatever happens to be true of the wrong team.
+  if (
+    urlRef != null &&
+    urlRef.teamKey.toUpperCase() !== data.team.key.toUpperCase()
+  ) {
+    // Resolving it anyway would find the wrong team's cycle with the same
+    // number — plausible-looking and wrong.
+    throw new ValidationError(
+      `That cycle URL is for team ${urlRef.teamKey}, but this command is working in team ${data.team.key}.`,
+      { suggestion: `Pass --team ${urlRef.teamKey}.` },
+    )
+  }
   if (!data.team.cyclesEnabled) {
     throw new ValidationError(
       `Cycles are not enabled for team ${data.team.key}`,
@@ -2427,7 +2521,25 @@ export async function getCycleIdByNameOrNumber(
     cycles.push(...(page.team.cycles?.nodes || []))
     pageInfo = page.team.cycles?.pageInfo
   }
-  const keyword = cycleNameOrNumber.toLowerCase()
+  let reference = cycleNameOrNumber
+  if (urlRef != null) {
+    if (typeof urlRef.cycle === "number") {
+      // Match the number alone. The general path below also matches cycle
+      // names, so a cycle that happened to be named "5" could win there.
+      const cycleNumber = urlRef.cycle
+      const byNumber = cycles.find((c) => c.number === cycleNumber)
+      if (!byNumber) {
+        throw new NotFoundError(
+          "Cycle",
+          `#${cycleNumber} in team ${data.team.key}`,
+        )
+      }
+      return byNumber.id
+    }
+    reference = urlRef.cycle
+  }
+
+  const keyword = reference.toLowerCase()
 
   // Reserved keywords take precedence over coincidental cycle names; use the
   // cycle number to reach a cycle literally named "next"/"previous"/"active".
@@ -2470,16 +2582,16 @@ export async function getCycleIdByNameOrNumber(
     return previous.id
   }
 
-  if (/^[+-]\d+$/.test(cycleNameOrNumber)) {
-    const offset = Number(cycleNameOrNumber)
+  if (/^[+-]\d+$/.test(reference)) {
+    const offset = Number(reference)
     if (!Number.isSafeInteger(offset)) {
       throw new ValidationError(
-        `Cycle offset ${cycleNameOrNumber} is out of range`,
+        `Cycle offset ${reference} is out of range`,
       )
     }
     if (!data.team.activeCycle) {
       throw new ValidationError(
-        `Cannot resolve relative cycle ${cycleNameOrNumber}: the team has no active cycle`,
+        `Cannot resolve relative cycle ${reference}: the team has no active cycle`,
         {
           suggestion:
             "Use 'next', a cycle number, or a cycle name while no cycle is active.",
@@ -2491,7 +2603,7 @@ export async function getCycleIdByNameOrNumber(
     if (!target) {
       throw new NotFoundError(
         "Cycle",
-        `${cycleNameOrNumber} (cycle ${targetNumber})`,
+        `${reference} (cycle ${targetNumber})`,
       )
     }
     return target.id
@@ -2500,10 +2612,10 @@ export async function getCycleIdByNameOrNumber(
   const match = cycles.find(
     (c) =>
       (c.name != null && c.name.toLowerCase() === keyword) ||
-      String(c.number) === cycleNameOrNumber,
+      String(c.number) === reference,
   )
   if (!match) {
-    throw new NotFoundError("Cycle", cycleNameOrNumber)
+    throw new NotFoundError("Cycle", reference)
   }
   return match.id
 }
@@ -2514,22 +2626,59 @@ export async function getCycleIdByNameOrNumber(
  * ValidationError when the name is ambiguous — initiative names are not
  * unique, so an ambiguous match must not pick silently.
  */
-export async function resolveInitiativeId(input: string): Promise<string> {
-  if (isLinearUuid(input)) return input
-
+/**
+ * Look up an initiative by slug ID and nothing else. See
+ * [[findProjectIdBySlug]]: a URL's slug must not fall through to a name lookup
+ * that a same-named initiative could win.
+ */
+export async function findInitiativeIdBySlug(
+  slugId: string,
+  options: { includeArchived?: boolean } = {},
+): Promise<string | undefined> {
   const client = getGraphQLClient()
-
   const slugQuery = gql(/* GraphQL */ `
-    query ResolveInitiativeBySlug($slugId: String!) {
-      initiatives(filter: { slugId: { eq: $slugId } }) {
+    query ResolveInitiativeBySlug($slugId: String!, $includeArchived: Boolean) {
+      initiatives(
+        filter: { slugId: { eq: $slugId } }
+        includeArchived: $includeArchived
+      ) {
         nodes {
           id
         }
       }
     }
   `)
-  const slugData = await client.request(slugQuery, { slugId: input })
-  const slugMatch = slugData.initiatives?.nodes[0]?.id
+  // Commands that act on archived initiatives (unarchive, delete) must be able
+  // to find them by URL too; the others keep Linear's default of hiding them.
+  const slugData = await client.request(slugQuery, {
+    slugId,
+    includeArchived: options.includeArchived ?? false,
+  })
+  return slugData.initiatives?.nodes[0]?.id
+}
+
+export async function resolveInitiativeId(input: string): Promise<string> {
+  const urlRef = expectLinearUrlKind(
+    input,
+    "initiative",
+    "an initiative URL, UUID, slug ID, or exact name",
+  )
+  if (urlRef != null) {
+    const fromUrl = await findInitiativeIdBySlug(urlRef.slugId)
+    if (fromUrl == null) {
+      throw new NotFoundError("Initiative", input, {
+        suggestion:
+          "The initiative in that URL may have been deleted, or be in a workspace this key cannot see.",
+      })
+    }
+    return fromUrl
+  }
+
+  if (isLinearUuid(input)) return input
+
+  const client = getGraphQLClient()
+
+  const slugMatch = await findInitiativeIdBySlug(input)
   if (slugMatch) return slugMatch
 
   const nameQuery = gql(/* GraphQL */ `
@@ -2570,6 +2719,7 @@ export async function resolveInitiativeId(input: string): Promise<string> {
  * unique human identifier, so an ambiguous match must not pick silently.
  */
 export async function resolveReleaseId(input: string): Promise<string> {
+  rejectLinearUrl(input, "a release name, version, or UUID")
   if (isLinearUuid(input)) return input
 
   const client = getGraphQLClient()
diff --git a/src/utils/templates.ts b/src/utils/templates.ts
index 87051e0e2..3fb0e31a3 100644
--- a/src/utils/templates.ts
+++ b/src/utils/templates.ts
@@ -2,6 +2,7 @@ import { gql } from "../__codegen__/gql.ts"
 import type { GetTemplatesQuery } from "../__codegen__/graphql.ts"
 import { getGraphQLClient } from "./graphql.ts"
 import { isLinearUuid } from "./linear.ts"
+import { rejectLinearUrl } from "./linear-url.ts"
 import {
   CliError,
   isClientError,
@@ -221,6 +222,7 @@ export async function resolveTemplate(
   reference: string,
   scope?: TemplateScope,
 ): Promise<Template> {
+  rejectLinearUrl(reference, "a template name or UUID")
   if (isLinearUuid(reference)) {
     const template = await fetchTemplate(reference)
     if (scope != null) {
diff --git a/test/commands/document/document-list.test.ts b/test/commands/document/document-list.test.ts
index 282eb9479..406a64e84 100644
--- a/test/commands/document/document-list.test.ts
+++ b/test/commands/document/document-list.test.ts
@@ -6,6 +6,7 @@ import {
 } from "../../../src/commands/document/document-list.ts"
 import { MockLinearServer } from "../../utils/mock_linear_server.ts"
 import { commonDenoArgs } from "../../utils/test-helpers.ts"
+import { assertStringIncludes } from "@std/assert"
 
 // Test help output
 await snapshotTest({
@@ -526,3 +527,76 @@ await snapshotTest({
     }
   },
 })
+
+// `--issue` on the document commands resolves through its own lookup rather
+// than `getIssueIdentifier`. Both mocks are pinned to the extracted identifier:
+// if the whole URL were uppercased and sent, as it once was, nothing would
+// match and the command would fail.
+Deno.test("document list --issue accepts a pasted issue URL", async () => {
+  const previousWorkspace = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", "url-test-workspace")
+  const server = new MockLinearServer([
+    {
+      queryName: "GetIssueForDocumentTarget",
+      variables: { id: "TC-123" },
+      response: { data: { issue: { id: "issue-uuid-1" } } },
+    },
+    {
+      queryName: "ListDocuments",
+      variables: {
+        filter: { issue: { id: { eq: "issue-uuid-1" } } },
+        first: 50,
+      },
+      response: {
+        data: {
+          documents: {
+            nodes: [{
+              id: "doc-2",
+              title: "Migration Runbook",
+              slugId: "a1c27f6d8e04",
+              url:
+                "https://linear.app/test/document/migration-runbook-a1c27f6d8e04",
+              updatedAt: "2026-01-20T14:15:00Z",
+              project: null,
+              issue: { identifier: "TC-123", title: "Plan the migration" },
+              initiative: null,
+              team: null,
+              cycle: null,
+              release: null,
+              creator: { name: "Jane Smith" },
+            }],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      },
+    },
+  ])
+
+  const originalLog = console.log
+  const output: string[] = []
+  console.log = (...args: unknown[]) => {
+    output.push(args.map(String).join(" "))
+  }
+  try {
+    await server.start()
+    Deno.env.set("LINEAR_GRAPHQL_ENDPOINT", server.getEndpoint())
+    Deno.env.set("LINEAR_API_KEY", "Bearer test-token")
+    await listCommand.parse([
+      "--issue",
+      "https://linear.app/url-test-workspace/issue/TC-123/plan-the-migration",
+      "--json",
+    ])
+  } finally {
+    console.log = originalLog
+    await server.stop()
+    Deno.env.delete("LINEAR_GRAPHQL_ENDPOINT")
+    Deno.env.delete("LINEAR_API_KEY")
+    if (previousWorkspace == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previousWorkspace)
+    }
+  }
+
+  assertStringIncludes(output.join("\n"), "Migration Runbook")
+})
diff --git a/test/commands/initiative/initiative-unarchive.test.ts b/test/commands/initiative/initiative-unarchive.test.ts
new file mode 100644
index 000000000..5a4573a03
--- /dev/null
+++ b/test/commands/initiative/initiative-unarchive.test.ts
@@ -0,0 +1,87 @@
+import { assertStringIncludes } from "@std/assert"
+import { unarchiveCommand } from "../../../src/commands/initiative/initiative-unarchive.ts"
+import { setupMockLinearServer } from "../../utils/test-helpers.ts"
+
+/**
+ * An archived initiative is only visible to lookups that ask for archived
+ * records. A URL's slug is resolved strictly — never by name — and that strict
+ * lookup once omitted `includeArchived`, so the one command whose whole job is
+ * archived initiatives could not find one by URL. The slug mock below only
+ * answers when `includeArchived` is true.
+ */
+Deno.test("initiative unarchive finds an archived initiative by its URL", async () => {
+  const previousWorkspace = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", "url-test-workspace")
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveInitiativeBySlug",
+      variables: { slugId: "43bc13e544d9", includeArchived: true },
+      response: {
+        data: {
+          initiatives: {
+            nodes: [{ id: "c44f9540-2e02-42c9-bec9-82e4e9529bc0" }],
+          },
+        },
+      },
+    },
+    {
+      queryName: "GetInitiativeForUnarchive",
+      variables: { id: "c44f9540-2e02-42c9-bec9-82e4e9529bc0" },
+      response: {
+        data: {
+          initiatives: {
+            nodes: [{
+              id: "c44f9540-2e02-42c9-bec9-82e4e9529bc0",
+              slugId: "43bc13e544d9",
+              name: "Archived initiative",
+              archivedAt: "2026-09-20T00:00:00Z",
+            }],
+          },
+        },
+      },
+    },
+    {
+      queryName: "UnarchiveInitiative",
+      variables: { id: "c44f9540-2e02-42c9-bec9-82e4e9529bc0" },
+      response: {
+        data: {
+          initiativeUnarchive: {
+            success: true,
+            entity: {
+              id: "c44f9540-2e02-42c9-bec9-82e4e9529bc0",
+              slugId: "43bc13e544d9",
+              name: "Archived initiative",
+              url:
+                "https://linear.app/url-test-workspace/initiative/archived-initiative-43bc13e544d9",
+            },
+          },
+        },
+      },
+    },
+  ])
+
+  const originalLog = console.log
+  const output: string[] = []
+  console.log = (...args: unknown[]) => {
+    output.push(args.map(String).join(" "))
+  }
+  try {
+    await unarchiveCommand.parse([
+      "https://linear.app/url-test-workspace/initiative/archived-initiative-43bc13e544d9",
+      "--force",
+    ])
+  } finally {
+    console.log = originalLog
+    await cleanup()
+    if (previousWorkspace == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previousWorkspace)
+    }
+  }
+
+  assertStringIncludes(
+    output.join("\n"),
+    "Unarchived initiative: Archived initiative",
+  )
+})
diff --git a/test/commands/issue/issue-url-reference.test.ts b/test/commands/issue/issue-url-reference.test.ts
new file mode 100644
index 000000000..06aa418a9
--- /dev/null
+++ b/test/commands/issue/issue-url-reference.test.ts
@@ -0,0 +1,101 @@
+import { assertEquals, assertStringIncludes } from "@std/assert"
+import { linkCommand } from "../../../src/commands/issue/issue-link.ts"
+import { setupMockLinearServer } from "../../utils/test-helpers.ts"
+
+const ISSUE_URL = "https://linear.app/url-test-workspace/issue/ENG-123/a-title"
+
+function withWorkspace(): () => void {
+  const previous = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", "url-test-workspace")
+  return () => {
+    if (previous == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previous)
+    }
+  }
+}
+
+/**
+ * `issue link` treats a single URL argument as the thing being linked, not as
+ * the issue to link it to. A Linear URL is a perfectly reasonable thing to
+ * attach to an issue, so URL-as-identifier must not reach this argument.
+ */
+Deno.test("issue link still treats a lone Linear URL as the link target", async () => {
+  const restore = withWorkspace()
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetIssueId",
+      variables: { id: "ENG-999" },
+      response: { data: { issue: { id: "issue-uuid-999" } } },
+    },
+    {
+      queryName: "AttachmentLinkURL",
+      response: {
+        data: {
+          attachmentLinkURL: {
+            success: true,
+            attachment: { id: "a1", title: "Linked", url: ISSUE_URL },
+          },
+        },
+      },
+    },
+  ])
+
+  const originalLog = console.log
+  const output: string[] = []
+  console.log = (...args: unknown[]) => {
+    output.push(args.map(String).join(" "))
+  }
+  try {
+    // Two arguments: the first is the issue, the second is the URL to attach.
+    // If the lone-URL branch regressed, the Linear URL would be consumed as an
+    // identifier and this attachment would never be created.
+    await linkCommand.parse(["ENG-999", ISSUE_URL])
+  } finally {
+    console.log = originalLog
+    restore()
+    await cleanup()
+  }
+
+  assertStringIncludes(output.join("\n"), "Linked")
+})
+
+/**
+ * Resolution has to happen inside each action's `try`, or the ValidationError it
+ * raises for a wrong-kind URL escapes `cli.parse` and prints a stack trace
+ * instead of the clean message handleError produces.
+ */
+Deno.test("a wrong-kind URL is reported, not thrown out of the action", async () => {
+  const { commentListCommand } = await import(
+    "../../../src/commands/document/document-comment-list.ts"
+  )
+  const restore = withWorkspace()
+  const { cleanup } = await setupMockLinearServer([])
+
+  const originalError = console.error
+  const originalExit = Deno.exit
+  const errors: string[] = []
+  let exitCode: number | undefined
+  console.error = (...args: unknown[]) => {
+    errors.push(args.map(String).join(" "))
+  }
+  Deno.exit = ((code?: number) => {
+    exitCode = code
+    throw new Error("exit")
+  }) as typeof Deno.exit
+
+  try {
+    await commentListCommand.parse([ISSUE_URL])
+  } catch (error) {
+    if (!(error instanceof Error) || error.message !== "exit") throw error
+  } finally {
+    console.error = originalError
+    Deno.exit = originalExit
+    restore()
+    await cleanup()
+  }
+
+  assertEquals(exitCode, 1)
+  assertStringIncludes(errors.join("\n"), "is an issue URL, not a document URL")
+})
diff --git a/test/utils/comments.test.ts b/test/utils/comments.test.ts
index ce6803721..e4e2be179 100644
--- a/test/utils/comments.test.ts
+++ b/test/utils/comments.test.ts
@@ -1,4 +1,4 @@
-import { assertEquals, assertRejects } from "@std/assert"
+import { assertEquals, assertRejects, assertThrows } from "@std/assert"
 import { stripAnsiCode } from "@std/fmt/colors"
 import { stub } from "@std/testing/mock"
 import {
@@ -163,3 +163,21 @@ Deno.test("renderCommentThreads keeps a reply whose parent is absent", () => {
   // It is not misrepresented as a root comment.
   assertEquals(lines.some((line) => line.includes("commented")), false)
 })
+
+Deno.test("buildCommentCreateInput refuses a comment link as the reply parent", () => {
+  // Every comment-add command's --reply-to arrives here. A comment link carries
+  // only the first eight characters of the comment's ID, so sending it as
+  // `parentId` could only fail at the API with a much less useful message.
+  assertThrows(
+    () =>
+      buildCommentCreateInput(
+        { kind: "issue", issueId: "issue-uuid" },
+        {
+          body: "reply",
+          parentId: "https://linear.app/acme/issue/ENG-1/x#comment-325482e4",
+        },
+      ),
+    ValidationError,
+    "first eight characters",
+  )
+})
diff --git a/test/utils/linear-url.property.test.ts b/test/utils/linear-url.property.test.ts
new file mode 100644
index 000000000..bf894c452
--- /dev/null
+++ b/test/utils/linear-url.property.test.ts
@@ -0,0 +1,440 @@
+/**
+ * Property-based fuzzing for the Linear URL parser.
+ *
+ * `parseLinearUrl` is a pure function from an arbitrary user-pasted string to a
+ * typed classification, which makes it the kind of narrow, deterministic
+ * boundary where generative testing pays off. Each property below is an oracle
+ * the parser has to keep for every input, not just the handful in
+ * `linear-url.test.ts`:
+ *
+ * - round-trip: any reference, rendered the way people paste it, parses back
+ * - containment: only `linear.app` itself is ever read as Linear
+ * - fall-through: ordinary IDs, slugs and names are never mistaken for URLs
+ * - totality: junk and mutated URLs never throw, and whatever comes out is
+ *   well-formed
+ * - kind checking: the right kind returns the reference, any other kind is a
+ *   ValidationError, and nothing else ever escapes
+ *
+ * Each run uses a fresh random seed, so CI keeps exploring new inputs. A
+ * failure prints the seed and a shrunk counterexample. To replay one exactly:
+ *
+ *   FC_SEED=<seed> FC_PATH=<path> deno task test test/utils/linear-url.property.test.ts
+ *
+ * For a longer campaign than CI runs, raise FC_NUM_RUNS (e.g. 200000). Any
+ * failure found that way should also be added to linear-url.test.ts as a
+ * plain regression case.
+ */
+import fc from "fast-check"
+import { assertEquals, assertThrows } from "@std/assert"
+import {
+  expectLinearUrlKind,
+  type LinearUrlParse,
+  type LinearUrlRef,
+  parseLinearUrl,
+} from "../../src/utils/linear-url.ts"
+import { ValidationError } from "../../src/utils/errors.ts"
+
+function runParameters(): fc.Parameters<unknown> {
+  const seed = Deno.env.get("FC_SEED")
+  const path = Deno.env.get("FC_PATH")
+  const numRuns = Deno.env.get("FC_NUM_RUNS")
+  return {
+    numRuns: numRuns == null ? 1000 : Number(numRuns),
+    ...(seed == null ? {} : { seed: Number(seed) }),
+    ...(path == null ? {} : { path }),
+  }
+}
+
+const KINDS: ReadonlyArray<LinearUrlRef["kind"]> = [
+  "issue",
+  "project",
+  "document",
+  "initiative",
+  "team",
+  "cycle",
+]
+
+// ---------------------------------------------------------------------------
+// Generators for the pieces a real Linear URL is made of.
+
+const workspaceArb = fc.stringMatching(/^[a-z0-9][a-z0-9-]{0,19}$/)
+const teamKeyArb = fc.stringMatching(/^[A-Z][A-Z0-9]{0,6}$/)
+const slugIdArb = fc.stringMatching(/^[0-9a-f]{12}$/)
+const shortHexArb = fc.stringMatching(/^[0-9a-f]{8}$/)
+/**
+ * The decorative part of `{name-slug}-{slugId}`. It is deliberately allowed to
+ * look like hex, run to extra dashes, or be empty — the slug ID must still be
+ * found at the end.
+ */
+const nameSlugArb = fc.stringMatching(/^[a-z0-9-]{0,40}$/)
+const titleSlugArb = fc.option(fc.stringMatching(/^[a-z0-9-]{1,40}$/), {
+  nil: undefined,
+})
+
+function withSlug(nameSlug: string, slugId: string): string {
+  return nameSlug === "" ? slugId : `${nameSlug}-${slugId}`
+}
+
+/** A URL path (after the workspace) and the reference it should parse to. */
+type Case = { path: string; anchor: string; expected: LinearUrlRef }
+
+function caseArb(workspace: string): fc.Arbitrary<Case> {
+  const lowerKey = (key: string, lower: boolean) =>
+    lower ? key.toLowerCase() : key
+
+  const issue = fc.record({
+    teamKey: teamKeyArb,
+    number: fc.integer({ min: 1, max: 1_000_000 }),
+    title: titleSlugArb,
+    comment: fc.option(shortHexArb, { nil: undefined }),
+    lower: fc.boolean(),
+  }).map(({ teamKey, number, title, comment, lower }): Case => ({
+    path: `issue/${lowerKey(teamKey, lower)}-${number}${
+      title == null ? "" : `/${title}`
+    }`,
+    anchor: comment == null ? "" : `#comment-${comment}`,
+    expected: {
+      kind: "issue",
+      workspace,
+      identifier: `${teamKey}-${number}`,
+      ...(comment == null ? {} : { commentIdPrefix: comment }),
+    },
+  }))
+
+  const project = fc.record({
+    name: nameSlugArb,
+    slugId: slugIdArb,
+    tab: fc.constantFrom("", "overview", "issues", "updates", "activity"),
+    update: fc.option(shortHexArb, { nil: undefined }),
+  }).map(({ name, slugId, tab, update }): Case => ({
+    path: `project/${withSlug(name, slugId)}${tab === "" ? "" : `/${tab}`}`,
+    anchor: update == null ? "" : `#project-update-${update}`,
+    expected: { kind: "project", workspace, slugId },
+  }))
+
+  const documentOrInitiative = fc.record({
+    kind: fc.constantFrom<"document" | "initiative">("document", "initiative"),
+    name: nameSlugArb,
+    slugId: slugIdArb,
+  }).map(({ kind, name, slugId }): Case => ({
+    path: `${kind}/${withSlug(name, slugId)}`,
+    anchor: "",
+    expected: { kind, workspace, slugId },
+  }))
+
+  const team = fc.record({
+    teamKey: teamKeyArb,
+    page: fc.constantFrom(
+      "",
+      "overview",
+      "all",
+      "active",
+      "cycles",
+      "projects/all",
+      "views/issues",
+    ),
+    lower: fc.boolean(),
+  }).map(({ teamKey, page, lower }): Case => ({
+    path: `team/${lowerKey(teamKey, lower)}${page === "" ? "" : `/${page}`}`,
+    anchor: "",
+    expected: { kind: "team", workspace, teamKey },
+  }))
+
+  const cycle = fc.record({
+    teamKey: teamKeyArb,
+    which: fc.oneof(
+      fc.integer({ min: 1, max: 100_000 }),
+      fc.constantFrom<"active" | "upcoming">("active", "upcoming"),
+    ),
+  }).map(({ teamKey, which }): Case => ({
+    path: `team/${teamKey}/cycle/${which}`,
+    anchor: "",
+    expected: {
+      kind: "cycle",
+      workspace,
+      teamKey,
+      // The app's "upcoming" is the cycle the CLI calls "next".
+      cycle: which === "upcoming" ? "next" : which,
+    },
+  }))
+
+  return fc.oneof(issue, project, documentOrInitiative, team, cycle)
+}
+
+/** The ways the same URL arrives from a browser, the app, or a sloppy paste. */
+const presentationArb = fc.record({
+  scheme: fc.constantFrom("https://", "http://", ""),
+  host: fc.constantFrom(
+    "linear.app",
+    "www.linear.app",
+    "LINEAR.APP",
+    "Linear.App",
+  ),
+  trailingSlash: fc.boolean(),
+  query: fc.constantFrom("", "?utm_source=slack", "?a=1&b=2", "?"),
+  padding: fc.constantFrom("", " ", "  ", "\t", "\n"),
+})
+
+type Rendered = { url: string; expected: LinearUrlRef }
+
+const renderedArb: fc.Arbitrary<Rendered> = workspaceArb.chain((workspace) =>
+  fc.tuple(caseArb(workspace), presentationArb).map(
+    ([{ path, anchor, expected }, p]) => ({
+      url: `${p.padding}${p.scheme}${p.host}/${workspace}/${path}${
+        p.trailingSlash ? "/" : ""
+      }${p.query}${anchor}${p.padding}`,
+      expected,
+    }),
+  )
+)
+
+// ---------------------------------------------------------------------------
+// Properties.
+
+Deno.test("property: every reference survives the ways people paste its URL", () => {
+  fc.assert(
+    fc.property(renderedArb, ({ url, expected }) => {
+      assertEquals(parseLinearUrl(url), { status: "ok", ref: expected })
+    }),
+    runParameters(),
+  )
+})
+
+/**
+ * The WHATWG URL parser is the reference: whatever host it sees, only the two
+ * real Linear hosts may be treated as Linear. This is the check that stops a
+ * lookalike domain from being read as a reference into the workspace.
+ */
+Deno.test("property: only linear.app itself is ever read as a Linear URL", () => {
+  const lookalikeHostArb = fc.tuple(
+    fc.constantFrom("", "www.", "app.", "sub.", "linear-", "x"),
+    fc.constantFrom("linear.app", "linear-app", "linearapp", "lineaR.app"),
+    fc.constantFrom("", ".", ".evil.com", ".app", "x", ":8443", "-cdn"),
+  ).map(([before, core, after]) => `${before}${core}${after}`)
+
+  const hostArb = fc.oneof(lookalikeHostArb, fc.domain())
+
+  fc.assert(
+    fc.property(
+      hostArb,
+      fc.constantFrom("https://", "http://"),
+      fc.constantFrom(
+        "/acme/issue/ENG-1/x",
+        "/acme/project/a-576342554a6e",
+        "/acme/team/ENG/cycle/5",
+      ),
+      (host, scheme, path) => {
+        const input = `${scheme}${host}${path}`
+        let reference: URL
+        try {
+          reference = new URL(input)
+        } catch {
+          // Not a URL at all, so it must fall through as ordinary input.
+          assertEquals(parseLinearUrl(input).status, "not-linear-url", input)
+          return
+        }
+        const real = ["linear.app", "www.linear.app"].includes(
+          reference.hostname.toLowerCase().replace(/\.$/, ""),
+        ) && reference.port === ""
+        if (!real) {
+          assertEquals(parseLinearUrl(input).status, "not-linear-url", input)
+        }
+      },
+    ),
+    runParameters(),
+  )
+})
+
+/**
+ * Every existing lookup — IDs, slug IDs, UUIDs, names — depends on ordinary
+ * input falling through untouched. Only input that plainly announces itself as
+ * a URL may be classified as one.
+ */
+Deno.test("property: ordinary identifiers and names are never mistaken for URLs", () => {
+  const nameArb = fc.string({ unit: "grapheme", maxLength: 60 }).filter(
+    (value) => {
+      const lead = value.trim().toLowerCase()
+      return !["http:", "https:", "linear.app/", "www.linear.app/"].some(
+        (prefix) => lead.startsWith(prefix),
+      )
+    },
+  )
+  const ordinaryArb = fc.oneof(
+    fc.tuple(teamKeyArb, fc.integer({ min: 1, max: 1_000_000 })).map((
+      [key, n],
+    ) => `${key}-${n}`),
+    slugIdArb,
+    fc.uuid(),
+    nameArb,
+  )
+
+  fc.assert(
+    fc.property(ordinaryArb, (value) => {
+      assertEquals(parseLinearUrl(value), { status: "not-linear-url" }, value)
+    }),
+    runParameters(),
+  )
+})
+
+/** Garbage in must still produce a well-formed classification, never a throw. */
+function assertWellFormed(parse: LinearUrlParse, input: string): void {
+  if (parse.status !== "ok") {
+    return
+  }
+  const { ref } = parse
+  switch (ref.kind) {
+    case "issue":
+      assertEquals(/^[A-Z0-9]+-[1-9][0-9]*$/.test(ref.identifier), true, input)
+      if (ref.commentIdPrefix != null) {
+        assertEquals(/^[0-9a-f]{8}$/.test(ref.commentIdPrefix), true, input)
+      }
+      return
+    case "project":
+    case "document":
+    case "initiative":
+      assertEquals(/^[0-9a-f]{12}$/.test(ref.slugId), true, input)
+      return
+    case "team":
+      assertEquals(ref.teamKey, ref.teamKey.toUpperCase(), input)
+      return
+    case "cycle":
+      assertEquals(ref.teamKey, ref.teamKey.toUpperCase(), input)
+      if (typeof ref.cycle === "number") {
+        assertEquals(
+          Number.isSafeInteger(ref.cycle) && ref.cycle > 0,
+          true,
+          input,
+        )
+      }
+      return
+    default: {
+      const unreachable: never = ref
+      throw new Error(`unhandled kind in ${JSON.stringify(unreachable)}`)
+    }
+  }
+}
+
+/**
+ * Start from a real, valid URL and damage it: insert, delete and replace
+ * characters anywhere. This reaches the parser's inner branches far more often
+ * than random strings, which almost never get past the host check.
+ */
+const mutatedArb: fc.Arbitrary<string> = fc.tuple(
+  renderedArb,
+  fc.array(
+    fc.record({
+      at: fc.nat(),
+      op: fc.constantFrom("insert", "delete", "replace"),
+      char: fc.constantFrom(
+        "/",
+        "-",
+        "#",
+        "?",
+        "%",
+        ".",
+        ":",
+        "@",
+        " ",
+        "a",
+        "Z",
+        "0",
+        "9",
+        "é",
+        "\\",
+        "%2F",
+        "%E0%A4%A",
+        "..",
+      ),
+    }),
+    { maxLength: 6 },
+  ),
+).map(([{ url }, edits]) =>
+  edits.reduce((current, { at, op, char }) => {
+    const i = current.length === 0 ? 0 : at % (current.length + 1)
+    switch (op) {
+      case "insert":
+        return current.slice(0, i) + char + current.slice(i)
+      case "delete":
+        return current.slice(0, i) + current.slice(i + 1)
+      case "replace":
+        return current.slice(0, i) + char + current.slice(i + 1)
+    }
+  }, url)
+)
+
+Deno.test("property: junk and damaged URLs never throw, and results are well-formed", () => {
+  const inputArb = fc.oneof(
+    mutatedArb,
+    fc.string({ unit: "binary", maxLength: 120 }),
+    fc.webUrl({ withQueryParameters: true, withFragments: true }),
+  )
+  fc.assert(
+    fc.property(inputArb, (input) => {
+      const parse = parseLinearUrl(input)
+      assertEquals(
+        ["not-linear-url", "unsupported", "ok"].includes(parse.status),
+        true,
+      )
+      assertWellFormed(parse, input)
+    }),
+    runParameters(),
+  )
+})
+
+function withWorkspace<T>(workspace: string, fn: () => T): T {
+  const previous = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", workspace)
+  try {
+    return fn()
+  } finally {
+    if (previous == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previous)
+    }
+  }
+}
+
+Deno.test("property: the right kind returns the reference and every other kind is refused", () => {
+  fc.assert(
+    fc.property(renderedArb, ({ url, expected }) => {
+      withWorkspace(expected.workspace, () => {
+        assertEquals(
+          expectLinearUrlKind(url, expected.kind, "a reference"),
+          expected,
+        )
+        for (const other of KINDS.filter((k) => k !== expected.kind)) {
+          assertThrows(
+            () => expectLinearUrlKind(url, other, "a reference"),
+            ValidationError,
+          )
+        }
+      })
+    }),
+    runParameters(),
+  )
+})
+
+/**
+ * Whatever a user pastes into any slot, the only failure that may escape is a
+ * ValidationError — which handleError turns into a clean message. A TypeError
+ * or URIError would surface as a stack trace instead.
+ */
+Deno.test("property: pasted junk only ever fails as a ValidationError", () => {
+  const inputArb = fc.oneof(
+    mutatedArb,
+    fc.string({ unit: "binary", maxLength: 120 }),
+  )
+  fc.assert(
+    fc.property(inputArb, fc.constantFrom(...KINDS), (input, kind) => {
+      withWorkspace("url-test-workspace", () => {
+        try {
+          expectLinearUrlKind(input, kind, "a reference")
+        } catch (error) {
+          assertEquals(error instanceof ValidationError, true, String(error))
+        }
+      })
+    }),
+    runParameters(),
+  )
+})
diff --git a/test/utils/linear-url.test.ts b/test/utils/linear-url.test.ts
new file mode 100644
index 000000000..ffecd045f
--- /dev/null
+++ b/test/utils/linear-url.test.ts
@@ -0,0 +1,391 @@
+import { assertEquals, assertThrows } from "@std/assert"
+import {
+  expectLinearUrlKind,
+  type LinearUrlParse,
+  parseLinearUrl,
+  rejectCommentUrl,
+  rejectLinearUrl,
+} from "../../src/utils/linear-url.ts"
+import { ValidationError } from "../../src/utils/errors.ts"
+
+/**
+ * The canonical shapes, copied from the `url` field Linear's own API returns.
+ * If Linear changes a shape, these are the cases that should break first.
+ */
+Deno.test("parseLinearUrl reads the URL shapes Linear itself produces", () => {
+  const cases: Array<[string, LinearUrlParse]> = [
+    [
+      "https://linear.app/schpet/issue/CLI-113/cycle-demo-safe-to-delete",
+      {
+        status: "ok",
+        ref: { kind: "issue", workspace: "schpet", identifier: "CLI-113" },
+      },
+    ],
+    [
+      "https://linear.app/schpet/project/triage-221-225-2026-05-22-576342554a6e",
+      {
+        status: "ok",
+        ref: { kind: "project", workspace: "schpet", slugId: "576342554a6e" },
+      },
+    ],
+    [
+      "https://linear.app/schpet/document/repro-225-document-bb0b3827273a",
+      {
+        status: "ok",
+        ref: { kind: "document", workspace: "schpet", slugId: "bb0b3827273a" },
+      },
+    ],
+    [
+      "https://linear.app/schpet/initiative/url-shape-probe-1e2f47b4f76d",
+      {
+        status: "ok",
+        ref: {
+          kind: "initiative",
+          workspace: "schpet",
+          slugId: "1e2f47b4f76d",
+        },
+      },
+    ],
+    [
+      "https://linear.app/schpet/issue/CLI-72/release-script#comment-325482e4",
+      {
+        status: "ok",
+        ref: {
+          kind: "issue",
+          workspace: "schpet",
+          identifier: "CLI-72",
+          commentIdPrefix: "325482e4",
+        },
+      },
+    ],
+    [
+      // A project-update link is the project as far as the CLI is concerned.
+      "https://linear.app/schpet/project/qa-test-project-b7112e0dcc53/activity#project-update-f0896970",
+      {
+        status: "ok",
+        ref: { kind: "project", workspace: "schpet", slugId: "b7112e0dcc53" },
+      },
+    ],
+  ]
+
+  for (const [url, expected] of cases) {
+    assertEquals(parseLinearUrl(url), expected, url)
+  }
+})
+
+Deno.test("parseLinearUrl accepts the variations people actually paste", () => {
+  const issue = {
+    status: "ok",
+    ref: { kind: "issue", workspace: "schpet", identifier: "CLI-113" },
+  } satisfies LinearUrlParse
+
+  // No scheme — copied from a browser's address bar.
+  assertEquals(parseLinearUrl("linear.app/schpet/issue/CLI-113/x"), issue)
+  // Surrounding whitespace from a sloppy paste.
+  assertEquals(
+    parseLinearUrl("  https://linear.app/schpet/issue/CLI-113/x  "),
+    issue,
+  )
+  // Host casing and www.
+  assertEquals(
+    parseLinearUrl("https://LINEAR.APP/schpet/issue/CLI-113/x"),
+    issue,
+  )
+  assertEquals(
+    parseLinearUrl("https://www.linear.app/schpet/issue/CLI-113/x"),
+    issue,
+  )
+  // Tracking parameters never affect identity.
+  assertEquals(
+    parseLinearUrl("https://linear.app/schpet/issue/CLI-113/x?foo=bar"),
+    issue,
+  )
+  // No title slug.
+  assertEquals(parseLinearUrl("https://linear.app/schpet/issue/CLI-113"), issue)
+  // A lowercase team key is normalised the way identifiers are everywhere else.
+  assertEquals(parseLinearUrl("https://linear.app/schpet/issue/cli-113"), issue)
+  // Read, never fetched, so plain http is fine.
+  assertEquals(
+    parseLinearUrl("http://linear.app/schpet/issue/CLI-113/x"),
+    issue,
+  )
+})
+
+Deno.test("parseLinearUrl leaves ordinary input alone", () => {
+  // Anything here that came back "unsupported" would break an existing lookup
+  // by turning a legitimate name into an error.
+  const ordinary = [
+    "CLI-113",
+    "Mobile launch",
+    "576342554a6e",
+    "85d3dad6-136e-49ff-9593-33dc4b22b5ee",
+    "",
+    "   ",
+    // A different host entirely — `issue link` depends on this staying inert.
+    "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/schpet/linear-cli/pull/290",
+    // Lookalike hosts must not be mistaken for Linear.
+    "https://linear.app.evil.example/schpet/issue/CLI-1",
+    "https://notlinear.app/schpet/issue/CLI-1",
+    "https://sub.linear.app/schpet/issue/CLI-1",
+    // A port or credentials mean this is not the real thing.
+    "https://linear.app:8443/schpet/issue/CLI-1",
+    "https://user:pw@linear.app/schpet/issue/CLI-1",
+    // Not an http(s) scheme.
+    "linear://schpet/issue/CLI-1",
+    // A project could genuinely be named this.
+    "some/name/with/slashes",
+  ]
+
+  for (const value of ordinary) {
+    assertEquals(
+      parseLinearUrl(value),
+      { status: "not-linear-url" },
+      value,
+    )
+  }
+})
+
+Deno.test("parseLinearUrl refuses Linear URLs it cannot turn into a reference", () => {
+  // Each of these would otherwise be looked up as a name and reported as
+  // "not found: https://…", which is the confusion this module removes.
+  const unusable = [
+    "https://linear.app/schpet/settings/members",
+    "https://linear.app/schpet/search?q=hello",
+    "https://linear.app/schpet",
+    "https://linear.app/schpet/issue",
+    "https://linear.app/schpet/issue/not-an-identifier/x",
+    // The slug ID is the part that identifies the entity; without it there is
+    // nothing to look up.
+    "https://linear.app/schpet/project/no-slug-here",
+    "https://linear.app/schpet/project/short-abc123",
+    // A page under a project that is not the project.
+    "https://linear.app/schpet/project/qa-test-project-b7112e0dcc53/settings",
+    // An anchor we cannot read might mean something we would silently ignore.
+    "https://linear.app/schpet/issue/CLI-1/x#activity",
+    "https://linear.app/schpet/issue/CLI-1/x#comment-zzzz",
+    "https://linear.app/schpet/team",
+    "https://linear.app/schpet/team/CLI/unknown-page",
+  ]
+
+  for (const value of unusable) {
+    assertEquals(parseLinearUrl(value).status, "unsupported", value)
+  }
+})
+
+Deno.test("parseLinearUrl treats a project's tabs as the project", () => {
+  // A project URL is usually copied while looking at one of its tabs.
+  const project = {
+    status: "ok",
+    ref: { kind: "project", workspace: "schpet", slugId: "b7112e0dcc53" },
+  } satisfies LinearUrlParse
+  const base = "https://linear.app/schpet/project/qa-test-project-b7112e0dcc53"
+  for (const tab of ["", "/overview", "/issues", "/updates", "/activity"]) {
+    assertEquals(parseLinearUrl(base + tab), project, tab || "(bare)")
+  }
+  // Anything else under a project is not assumed to be the project.
+  assertEquals(parseLinearUrl(base + "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/settings").status, "unsupported")
+})
+
+Deno.test("parseLinearUrl treats a team's own pages as the team", () => {
+  const team = {
+    status: "ok",
+    ref: { kind: "team", workspace: "schpet", teamKey: "CLI" },
+  } satisfies LinearUrlParse
+
+  for (
+    const url of [
+      "https://linear.app/schpet/team/CLI",
+      // The team's home page, copied from the app's sidebar.
+      "https://linear.app/schpet/team/CLI/overview",
+      "https://linear.app/schpet/team/CLI/all",
+      "https://linear.app/schpet/team/CLI/active",
+      "https://linear.app/schpet/team/CLI/cycles",
+      "https://linear.app/schpet/team/CLI/projects/all",
+      "https://linear.app/schpet/team/CLI/views/issues",
+      "https://linear.app/schpet/team/cli/settings",
+    ]
+  ) {
+    assertEquals(parseLinearUrl(url), team, url)
+  }
+})
+
+Deno.test("parseLinearUrl reads the cycle URLs the app produces", () => {
+  // Each shape here was copied out of the Linear app: the app addresses a
+  // cycle by number, or relatively as "active" or "upcoming". The CLI's own
+  // word for "upcoming" is "next".
+  const cycle = (value: number | "active" | "next"): LinearUrlParse => ({
+    status: "ok",
+    ref: { kind: "cycle", workspace: "schpet", teamKey: "CLI", cycle: value },
+  })
+
+  assertEquals(
+    parseLinearUrl("https://linear.app/schpet/team/CLI/cycle/5"),
+    cycle(5),
+  )
+  assertEquals(
+    parseLinearUrl("https://linear.app/schpet/team/CLI/cycle/active"),
+    cycle("active"),
+  )
+  assertEquals(
+    parseLinearUrl("https://linear.app/schpet/team/CLI/cycle/upcoming"),
+    cycle("next"),
+  )
+  // Team keys normalise the way they do everywhere else.
+  assertEquals(
+    parseLinearUrl("https://linear.app/schpet/team/cli/cycle/5"),
+    cycle(5),
+  )
+})
+
+Deno.test("parseLinearUrl refuses cycle URLs it has not seen the app produce", () => {
+  // "previous" was not observed in the app, so it is not guessed at.
+  for (
+    const url of [
+      "https://linear.app/schpet/team/CLI/cycle",
+      "https://linear.app/schpet/team/CLI/cycle/previous",
+      "https://linear.app/schpet/team/CLI/cycle/abc",
+      "https://linear.app/schpet/team/CLI/cycle/0",
+      "https://linear.app/schpet/team/CLI/cycle/5/issues",
+    ]
+  ) {
+    assertEquals(parseLinearUrl(url).status, "unsupported", url)
+  }
+})
+
+Deno.test("expectLinearUrlKind falls through for ordinary input", () => {
+  // undefined is what preserves every existing UUID / slug / name lookup.
+  assertEquals(expectLinearUrlKind("CLI-113", "issue", "an issue"), undefined)
+  assertEquals(
+    expectLinearUrlKind("Mobile launch", "project", "a project"),
+    undefined,
+  )
+})
+
+Deno.test("expectLinearUrlKind names what the URL actually points at", () => {
+  const error = assertThrows(
+    () =>
+      expectLinearUrlKind(
+        "https://linear.app/schpet/issue/CLI-113/x",
+        "project",
+        "a project URL, UUID, slug ID, or exact name",
+      ),
+    ValidationError,
+    "is an issue URL, not a project URL",
+  )
+  // The suggestion tells the user what to pass instead; it is a separate field
+  // from the message, and `handleError` prints it on its own line.
+  assertEquals(
+    error.suggestion,
+    "Pass a project URL, UUID, slug ID, or exact name.",
+  )
+})
+
+Deno.test("expectLinearUrlKind returns the extracted reference, never the URL", () => {
+  const ref = expectLinearUrlKind(
+    "https://linear.app/schpet/project/triage-221-225-2026-05-22-576342554a6e",
+    "project",
+    "a project",
+  )
+  // Sending the whole URL to GraphQL happens to work today through an
+  // undocumented server-side behavior; this pins the local extraction instead.
+  assertEquals(ref?.slugId, "576342554a6e")
+})
+
+Deno.test("rejectLinearUrl reports a URL a command cannot take", () => {
+  assertThrows(
+    () =>
+      rejectLinearUrl(
+        "https://linear.app/schpet/issue/CLI-113/x",
+        "a milestone name or UUID",
+      ),
+    ValidationError,
+    "does not take one",
+  )
+  // Ordinary input passes straight through.
+  rejectLinearUrl("Design complete", "a milestone name or UUID")
+})
+
+Deno.test("rejectCommentUrl explains why a comment link cannot identify a comment", () => {
+  assertThrows(
+    () =>
+      rejectCommentUrl(
+        "https://linear.app/schpet/issue/CLI-72/x#comment-325482e4",
+      ),
+    ValidationError,
+    "first eight characters",
+  )
+  // An issue URL without a comment anchor is somebody else's problem.
+  rejectCommentUrl("https://linear.app/schpet/issue/CLI-72/x")
+  rejectCommentUrl("325482e4-6d9f-4a97-8f6d-3fc5b4a1fb39")
+})
+
+/**
+ * Run with LINEAR_WORKSPACE and LINEAR_API_KEY pinned, then restore them. The
+ * suggestion depends on where the key comes from, so leaving either to the
+ * machine running the test would make it pass in one place and fail in another.
+ */
+function withAuthEnv(
+  env: { workspace: string; apiKey: string | undefined },
+  fn: () => void,
+): void {
+  const previous = {
+    workspace: Deno.env.get("LINEAR_WORKSPACE"),
+    apiKey: Deno.env.get("LINEAR_API_KEY"),
+  }
+  const apply = (name: string, value: string | undefined) =>
+    value == null ? Deno.env.delete(name) : Deno.env.set(name, value)
+  apply("LINEAR_WORKSPACE", env.workspace)
+  apply("LINEAR_API_KEY", env.apiKey)
+  try {
+    fn()
+  } finally {
+    apply("LINEAR_WORKSPACE", previous.workspace)
+    apply("LINEAR_API_KEY", previous.apiKey)
+  }
+}
+
+const FOREIGN_URL = "https://linear.app/acme/issue/ENG-1/x"
+
+Deno.test("expectLinearUrlKind refuses a URL from another workspace", () => {
+  // A value that cannot coincide with whatever workspace the machine running
+  // this test happens to be configured for.
+  withAuthEnv({ workspace: "url-test-workspace", apiKey: undefined }, () => {
+    const error = assertThrows(
+      () => expectLinearUrlKind(FOREIGN_URL, "issue", "an issue URL"),
+      ValidationError,
+      'That URL is for the "acme" workspace',
+    )
+    assertEquals(
+      error.suggestion,
+      'Pass --workspace acme, or use a URL from "url-test-workspace".',
+    )
+
+    // The same workspace, spelled differently, is still the same workspace.
+    assertEquals(
+      expectLinearUrlKind(
+        "https://linear.app/URL-TEST-WORKSPACE/issue/CLI-1/x",
+        "issue",
+        "an issue URL",
+      )?.identifier,
+      "CLI-1",
+    )
+  })
+})
+
+Deno.test("a workspace mismatch under LINEAR_API_KEY does not suggest --workspace alone", () => {
+  // The CLI refuses --workspace while LINEAR_API_KEY is set, so a bare
+  // "pass --workspace" would lead straight into a second error.
+  withAuthEnv(
+    { workspace: "url-test-workspace", apiKey: "lin_api_test" },
+    () => {
+      const error = assertThrows(
+        () => expectLinearUrlKind(FOREIGN_URL, "issue", "an issue URL"),
+        ValidationError,
+      )
+      assertEquals(
+        error.suggestion,
+        'LINEAR_API_KEY is set, and the CLI won\'t combine it with --workspace. Unset it and pass --workspace acme, or use a URL from "url-test-workspace".',
+      )
+    },
+  )
+})
diff --git a/test/utils/linear.test.ts b/test/utils/linear.test.ts
index 4a3c2d4cb..4268b1e9d 100644
--- a/test/utils/linear.test.ts
+++ b/test/utils/linear.test.ts
@@ -3,9 +3,14 @@ import { assertThrows } from "@std/assert"
 import {
   compareWorkflowStates,
   findTeam,
+  getCycleIdByNameOrNumber,
   getIssueIdentifier,
+  getIssueLabelIdByNameForTeam,
+  getProjectIdByName,
+  getProjectLabelIdByName,
   getStartedState,
   isLinearUuid,
+  lookupUserId,
   lowestPositionStateOfType,
   resolveInitiativeId,
   resolveMilestoneId,
@@ -1104,3 +1109,292 @@ Deno.test("resolveStateSelection - a page that never advances is an error, not a
     await cleanup()
   }
 })
+
+Deno.test("getProjectIdByName resolves a project URL by slug alone, never by name", async () => {
+  // A different project is *named* exactly the slug in the URL. The general
+  // lookup tries names first, so if the URL's slug went through it, this other
+  // project would win — and `project delete <url>` would delete it.
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetProjectIdByName",
+      variables: { name: "576342554a6e" },
+      response: {
+        data: { projects: { nodes: [{ id: "project-named-like-the-slug" }] } },
+      },
+    },
+    {
+      queryName: "GetProjectIdBySlugId",
+      variables: { slugId: "576342554a6e" },
+      response: {
+        data: { projects: { nodes: [{ id: "project-with-that-slug" }] } },
+      },
+    },
+  ])
+  try {
+    await withUrlWorkspace(async () => {
+      assertEquals(
+        await getProjectIdByName(
+          "https://linear.app/url-test-workspace/project/mobile-launch-576342554a6e",
+        ),
+        "project-with-that-slug",
+      )
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("resolveInitiativeId does not fall back to a name when a URL's slug misses", async () => {
+  // The initiative in the URL is gone, and another initiative happens to be
+  // named exactly its slug. Falling back to a name lookup would quietly hand
+  // back that other initiative.
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "ResolveInitiativeBySlug",
+      variables: { slugId: "1e2f47b4f76d" },
+      response: { data: { initiatives: { nodes: [] } } },
+    },
+    {
+      queryName: "ResolveInitiativeByName",
+      response: {
+        data: {
+          initiatives: {
+            nodes: [{
+              id: "initiative-named-like-the-slug",
+              name: "1e2f47b4f76d",
+              slugId: "aaaaaaaaaaaa",
+            }],
+          },
+        },
+      },
+    },
+  ])
+  try {
+    await withUrlWorkspace(async () => {
+      await assertRejects(
+        () =>
+          resolveInitiativeId(
+            "https://linear.app/url-test-workspace/initiative/gone-1e2f47b4f76d",
+          ),
+        NotFoundError,
+      )
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("getIssueIdentifier reads the identifier out of an issue URL", async () => {
+  const previousWorkspace = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", "url-test-workspace")
+  const { cleanup } = await setupMockLinearServer([])
+  try {
+    // No request should be needed: the identifier is in the path.
+    assertEquals(
+      await getIssueIdentifier(
+        "https://linear.app/url-test-workspace/issue/ENG-123/some-title",
+      ),
+      "ENG-123",
+    )
+    // A comment link still names its issue.
+    assertEquals(
+      await getIssueIdentifier(
+        "https://linear.app/url-test-workspace/issue/ENG-123/t#comment-325482e4",
+      ),
+      "ENG-123",
+    )
+  } finally {
+    await cleanup()
+    if (previousWorkspace == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previousWorkspace)
+    }
+  }
+})
+
+function cycleLookupResponse(
+  key: string,
+  cycles: Array<
+    { id: string; number: number; name: string | null; isNext?: boolean }
+  >,
+  options: { cyclesEnabled?: boolean; active?: string } = {},
+) {
+  const nodes = cycles.map((c) => ({
+    id: c.id,
+    number: c.number,
+    name: c.name,
+    startsAt: "2026-09-21T07:00:00.000Z",
+    isNext: c.isNext ?? false,
+    isPrevious: false,
+  }))
+  const active = nodes.find((n) => n.id === options.active) ?? null
+  return {
+    data: {
+      team: {
+        key,
+        cyclesEnabled: options.cyclesEnabled ?? true,
+        cycles: {
+          nodes,
+          pageInfo: { hasNextPage: false, endCursor: null },
+        },
+        activeCycle: active == null
+          ? null
+          : { id: active.id, number: active.number, name: active.name },
+      },
+    },
+  }
+}
+
+async function withUrlWorkspace<T>(fn: () => Promise<T>): Promise<T> {
+  const previous = Deno.env.get("LINEAR_WORKSPACE")
+  Deno.env.set("LINEAR_WORKSPACE", "url-test-workspace")
+  try {
+    return await fn()
+  } finally {
+    if (previous == null) {
+      Deno.env.delete("LINEAR_WORKSPACE")
+    } else {
+      Deno.env.set("LINEAR_WORKSPACE", previous)
+    }
+  }
+}
+
+Deno.test("getCycleIdByNameOrNumber reads a cycle URL's number as a number, never a name", async () => {
+  // Cycle #5 is *named* "7". The general lookup matches a name or a number, so
+  // handed "7" it would stop at #5. A URL's /cycle/7 means cycle number 7.
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetTeamCyclesForLookup",
+      response: cycleLookupResponse("CLI", [
+        { id: "cycle-named-seven", number: 5, name: "7" },
+        { id: "cycle-number-seven", number: 7, name: null },
+      ]),
+    },
+  ])
+  try {
+    await withUrlWorkspace(async () => {
+      assertEquals(
+        await getCycleIdByNameOrNumber(
+          "https://linear.app/url-test-workspace/team/CLI/cycle/7",
+          "team-cli",
+        ),
+        "cycle-number-seven",
+      )
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("getCycleIdByNameOrNumber reads the app's upcoming as next", async () => {
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetTeamCyclesForLookup",
+      response: cycleLookupResponse(
+        "CLI",
+        [
+          { id: "cycle-5", number: 5, name: null },
+          { id: "cycle-6", number: 6, name: null, isNext: true },
+        ],
+        { active: "cycle-5" },
+      ),
+    },
+  ])
+  try {
+    await withUrlWorkspace(async () => {
+      assertEquals(
+        await getCycleIdByNameOrNumber(
+          "https://linear.app/url-test-workspace/team/CLI/cycle/upcoming",
+          "team-cli",
+        ),
+        "cycle-6",
+      )
+      assertEquals(
+        await getCycleIdByNameOrNumber(
+          "https://linear.app/url-test-workspace/team/CLI/cycle/active",
+          "team-cli",
+        ),
+        "cycle-5",
+      )
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("getCycleIdByNameOrNumber reports a cycle URL for another team before anything else", async () => {
+  // FIG has cycles disabled. Without the ordering, the user would be told
+  // that, instead of the actual problem: the URL names a different team.
+  const { cleanup } = await setupMockLinearServer([
+    {
+      queryName: "GetTeamCyclesForLookup",
+      response: cycleLookupResponse("FIG", [], { cyclesEnabled: false }),
+    },
+  ])
+  try {
+    await withUrlWorkspace(async () => {
+      const error = await assertRejects(
+        () =>
+          getCycleIdByNameOrNumber(
+            "https://linear.app/url-test-workspace/team/CLI/cycle/5",
+            "team-fig",
+          ),
+        ValidationError,
+        "That cycle URL is for team CLI, but this command is working in team FIG.",
+      )
+      assertEquals(error.suggestion, "Pass --team CLI.")
+    })
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("label lookups refuse a pasted URL instead of searching for it as a name", async () => {
+  // No mocks: a request would come back as an unconfigured-query error, so
+  // passing here also proves the refusal happens before any lookup.
+  const { cleanup } = await setupMockLinearServer([])
+  const url = "https://linear.app/url-test-workspace/issue/ENG-1/x"
+  try {
+    await assertRejects(
+      () => getIssueLabelIdByNameForTeam(url, "ENG"),
+      ValidationError,
+      "this command does not take one",
+    )
+    await assertRejects(
+      () => getProjectLabelIdByName(url),
+      ValidationError,
+      "this command does not take one",
+    )
+  } finally {
+    await cleanup()
+  }
+})
+
+Deno.test("user and workflow-state lookups refuse a pasted URL", async () => {
+  // No mocks, so a lookup that reached the API would fail differently.
+  const { cleanup } = await setupMockLinearServer([])
+  const url = "https://linear.app/url-test-workspace/settings/members"
+  try {
+    // --assignee, --lead and --member all resolve through lookupUserId.
+    await assertRejects(
+      () => lookupUserId(url),
+      ValidationError,
+      "this command does not take one",
+    )
+    // --state on issue create/update.
+    assertThrows(
+      () => resolveWorkflowState([], url),
+      ValidationError,
+      "this command does not take one",
+    )
+    // --state on issue query/mine.
+    await assertRejects(
+      () => resolveStateSelection([url], { allTeams: true }),
+      ValidationError,
+      "this command does not take one",
+    )
+  } finally {
+    await cleanup()
+  }
+})