diff --git a/ai-code-doc.el b/ai-code-doc.el
index e9c7134d..9e0518f4 100644
--- a/ai-code-doc.el
+++ b/ai-code-doc.el
@@ -19,6 +19,9 @@
 (declare-function ai-code--format-repo-context-info "ai-code-utils")
 (declare-function ai-code--git-root "ai-code-utils" (&optional dir))
 (declare-function ai-code--ensure-files-directory "ai-code-utils")
+(declare-function ai-code--get-git-web-repo-url "ai-code-github" ())
+(declare-function magit-git-string "magit-git" (&rest args))
+(declare-function magit-git-success "magit-git" (&rest args))
 
 (defconst ai-code--architecture-document-choices
   '(("Derive Architecture Guardrails" . ai-code-derive-architecture-guardrails)
@@ -28,6 +31,21 @@
     ("Derive Test Context Document" . ai-code-derive-test-context))
   "Choices for `ai-code-derive-architecture-document'.")
 
+(defun ai-code--doc-emit-prompt (title prompt)
+  "Insert PROMPT under a TITLE headline at point, or send it to the AI.
+In `ai-code-prompt-mode' the prompt is written into the current buffer
+under the cursor, as an Org section at the level of the surrounding
+section, and no AI request is made.  Everywhere else PROMPT is handed to
+`ai-code--insert-prompt' as usual."
+  (if (derived-mode-p 'ai-code-prompt-mode)
+      (let ((level (or (org-current-level) 1)))
+        (unless (bolp)
+          (insert "\n"))
+        (insert (make-string level ?*) " " title " ")
+        (org-insert-time-stamp (current-time) t t)
+        (insert "\n" prompt "\n"))
+    (ai-code--insert-prompt prompt)))
+
 ;;;###autoload
 (defun ai-code-derive-architecture-document ()
   "Derive an architecture document by selecting one of the available options."
@@ -50,6 +68,48 @@ Default value is English."
   "Prompt for the language and append it to BASE-PROMPT."
   (concat base-prompt (format "\nGenerate the document in %s." (ai-code--read-document-language))))
 
+(defun ai-code--read-document-topic ()
+  "Ask which topic the document should cover.
+Return nil for an empty answer, which means the whole repository."
+  (let ((topic (string-trim
+                (read-string "Document topic (empty for whole repo): "))))
+    (unless (string-empty-p topic) topic)))
+
+(defun ai-code--topic-file-name (file-name topic)
+  "Return FILE-NAME with a slug and stable digest of TOPIC in its base name.
+The digest distinguishes topics whose readable slugs are identical.
+FILE-NAME is returned unchanged when TOPIC is nil, so whole-repository
+documents keep their well-known path and topic documents never overwrite
+them."
+  (if topic
+      (let ((slug (string-trim
+                   (downcase (replace-regexp-in-string "[^A-Za-z0-9]+" "-" topic))
+                   "-+" "-+")))
+        (format "%s-%s-%s.%s"
+                (file-name-sans-extension file-name)
+                (if (string-empty-p slug) "topic" slug)
+                (substring (secure-hash 'sha256
+                                        (encode-coding-string topic 'utf-8))
+                           0 12)
+                (file-name-extension file-name)))
+    file-name))
+
+(defun ai-code--append-document-topic (base-prompt topic)
+  "Append TOPIC scoping instructions to BASE-PROMPT.
+BASE-PROMPT is returned unchanged when TOPIC is nil."
+  (if topic
+      (concat base-prompt
+              (format "\nScope this document to the topic: %s.\n" topic)
+              "Only cover the code, tests, and docs relevant to this topic, and state which parts of the repository are out of scope.\n")
+    base-prompt))
+
+(defun ai-code--finalize-document-prompt (base-prompt topic)
+  "Append the TOPIC scope and the document language to BASE-PROMPT.
+The topic is added first so that the language question stays the last one
+asked before the prompt is edited."
+  (ai-code--append-document-language
+   (ai-code--append-document-topic base-prompt topic)))
+
 (defconst ai-code-ddd-context-output-relative-path
   ".ai.code.files/architecture/domain-context.org"
   "Repository-relative path for the derived DDD context document.")
@@ -95,6 +155,79 @@ Default value is English."
              "\n")
   "Initial Org template for architecture guardrails.")
 
+(defun ai-code--doc-github-repo-url ()
+  "Return the GitHub web URL of the current repository, or nil.
+Only GitHub remotes are recognized, because the generated links use the
+GitHub /blob/REVISION/ URL shape.  Any failure to reach Git or to parse the
+remote simply yields nil, which keeps documents on local file links."
+  (ignore-errors
+    (require 'ai-code-github)
+    (let ((url (ai-code--get-git-web-repo-url)))
+      (when (and url (string-match-p "\\`https://[^/]*github[^/]*/" url))
+        url))))
+
+(defun ai-code--doc-github-source-url ()
+  "Return a GitHub URL pinned to the analyzed commit, or nil.
+Require unchanged tracked files and an origin remote-tracking ref that
+contains HEAD.  Unpublished commits and Git failures use local links.
+Remote-tracking refs are checked locally; no network request is made."
+  (ignore-errors
+    (let* ((repo-url (ai-code--doc-github-repo-url))
+           (revision (and repo-url
+                          (magit-git-string "rev-parse" "--verify" "HEAD"))))
+      (when (and revision
+                 (magit-git-success "diff" "--quiet" revision "--")
+                 (magit-git-string "for-each-ref" "--format=%(refname)"
+                                   (concat "--contains=" revision)
+                                   "refs/remotes/origin/"))
+        (format "%s/blob/%s" repo-url revision)))))
+
+(defun ai-code--read-document-link-style ()
+  "Ask whether code references should link to GitHub or to local files.
+Return `github' or `local'.  Skip the question unless the analyzed commit
+is known on a GitHub origin and tracked files are unchanged."
+  (if (and (ai-code--doc-github-source-url)
+           (string-prefix-p
+            "g"
+            (string-trim (read-string "Link code references to (github or local): "
+                                      "github"))
+            t))
+      'github
+    'local))
+
+(defun ai-code--org-link-instruction (output-relative-path &optional link-style)
+  "Return the Org link rules for a document written to OUTPUT-RELATIVE-PATH.
+LINK-STYLE is `github' to prefer browser links, and anything else keeps
+the document on local file links.  Local links to files inside the
+repository are relative to the document itself, so one \"../\" is needed
+per directory level OUTPUT-RELATIVE-PATH sits in below the repository
+root; files outside the repository have no such anchor and are linked by
+absolute path."
+  (let* ((depth (length (split-string
+                         (or (file-name-directory output-relative-path) "")
+                         "/" t)))
+         (prefix (apply #'concat (make-list depth "../")))
+         (local-rules
+          (concat
+           (format "For a file inside this repository, use a relative link: [[file:%spath/to/file::symbol][description]].\n"
+                   prefix)
+           "For a file outside this repository, use an absolute link: [[file:/absolute/path/to/file::symbol][description]].\n"))
+         (source-url (and (eq link-style 'github)
+                          (ai-code--doc-github-source-url))))
+    (concat
+     "When referencing any file, folder, module, function, variable, type, or test case, you MUST turn it into a link so that the reader can jump from the document straight to the code.\n"
+     (if source-url
+         (concat
+          (format "Use a GitHub link, which opens in a browser: [[%s/path/to/file#L42][description]], anchored at the line where the definition starts.\n"
+                  source-url)
+          "Keep the commit ID in the URL; do not replace it with HEAD or a branch name. Verify that the referenced file and lines match this commit and that it is available on GitHub.\n"
+          "For files outside this repository, untracked, ignored, generated, or locally modified files, or when the commit is unavailable on GitHub, fall back to a local link instead:\n"
+          local-rules)
+       local-rules)
+     "Point each link at the definition: in a local link use ::symbol as the search target, and fall back to ::<line-number> only when there is no named symbol to search for.\n"
+     "Only link to paths and symbols you have actually confirmed in the repository; when you cannot confirm a definition, say so in plain text instead of guessing a link.\n"
+     "Add the link at the first mention in each section, in every table cell that names a file or a symbol, and in the explanatory notes that follow each diagram.\n")))
+
 (defun ai-code--ensure-architecture-document-file (file-name)
   "Ensure an architecture document named FILE-NAME exists and return its path."
   (let* ((files-dir (ai-code--ensure-files-directory))
@@ -105,8 +238,10 @@ Default value is English."
       (write-region "" nil target-file nil 'silent))
     target-file))
 
-(defun ai-code--derive-ddd-context-prompt (git-root)
-  "Build and return a formatted DDD context derivation prompt string for GIT-ROOT."
+(defun ai-code--derive-ddd-context-prompt (git-root &optional topic link-style)
+  "Build and return a formatted DDD context derivation prompt string for GIT-ROOT.
+TOPIC narrows the output file name when non-nil, and LINK-STYLE
+selects how code references are linked."
   (concat
    "Derive a lightweight Domain-Driven Design (DDD) style context document for this existing repository.\n"
    "Do not assume the repository already follows DDD today.\n"
@@ -115,10 +250,10 @@ Default value is English."
    "Mark uncertainty explicitly.\n"
    "Keep the output practical, concise, and useful for future AI coding tasks.\n"
    "Do not suggest large refactors unless you list them separately as optional future ideas.\n"
-   "When referencing any code file, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description_text]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory).\n"
+   (ai-code--org-link-instruction ai-code-ddd-context-output-relative-path link-style)
    (format "Repository root: %s\n" git-root)
    (format "Create or update the Org file at %s.\n\n"
-            ai-code-ddd-context-output-relative-path)
+            (ai-code--topic-file-name ai-code-ddd-context-output-relative-path topic))
    "Use this structure:\n"
    "* Domain Context\n\n"
    "** Purpose\n"
@@ -130,17 +265,19 @@ Default value is English."
    "** Testing Ideas\n"
    "** Notes and Uncertainties"))
 
-(defun ai-code--derive-test-context-prompt (git-root)
-  "Build and return Test Context prompt for GIT-ROOT."
+(defun ai-code--derive-test-context-prompt (git-root &optional topic link-style)
+  "Build and return Test Context prompt for GIT-ROOT.
+TOPIC narrows the output file name when non-nil, and LINK-STYLE
+selects how code references are linked."
   (concat
    "Derive a lightweight Test Context and Verification Guide document for this existing repository.\n"
    "Analyze the existing tests, test runner configuration, and mocking/verification patterns.\n"
    "Explain how the tests demonstrate and safeguard core business invariants.\n"
    "Keep the output practical, concise, and useful for future AI coding tasks.\n"
-   "When referencing any test file, source file, test case, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description_text]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory).\n"
+   (ai-code--org-link-instruction ai-code-test-context-output-relative-path link-style)
    (format "Repository root: %s\n" git-root)
    (format "Create or update the Org file at %s.\n\n"
-            ai-code-test-context-output-relative-path)
+            (ai-code--topic-file-name ai-code-test-context-output-relative-path topic))
    "Use this structure:\n"
    "* Test Context and Verification Guide\n\n"
    "** Purpose\n"
@@ -151,8 +288,10 @@ Default value is English."
    "** Coverage Gaps & Actionable Testing Ideas\n"
    "** Notes and Uncertainties"))
 
-(defun ai-code--derive-c4-plantuml-prompt (git-root)
-  "Build and return a C4 PlantUML architecture document prompt for GIT-ROOT."
+(defun ai-code--derive-c4-plantuml-prompt (git-root &optional topic link-style)
+  "Build and return a C4 PlantUML architecture document prompt for GIT-ROOT.
+TOPIC narrows the output file name when non-nil, and LINK-STYLE
+selects how code references are linked."
   (concat
    "Derive a C4-style architecture overview document for this existing repository.\n"
    "Generate the document as Org mode and embed PlantUML C4 diagrams in Org Babel source blocks.\n"
@@ -162,13 +301,13 @@ Default value is English."
    "Mark uncertain boundaries, relationships, and naming choices explicitly.\n"
    "Prefer fewer boxes and clearer relationships over large, noisy diagrams.\n"
    "Use C4 only as an architectural draft for human review.\n"
-   "When referencing any code file, folder, module, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description_text]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory).\n"
+   (ai-code--org-link-instruction ai-code-c4-plantuml-output-relative-path link-style)
    "For every diagram, include explanatory notes after the PlantUML block that summarize what the diagram shows and what remains uncertain.\n"
    "Use Org Babel blocks like #+begin_src plantuml :file c4-context.svg :exports both and include @startuml / @enduml inside each block.\n"
    "Use PlantUML C4 includes such as !include <C4/C4_Context>, !include <C4/C4_Container>, and !include <C4/C4_Component> when appropriate.\n"
    (format "Repository root: %s\n" git-root)
    (format "Create or update the Org file at %s.\n\n"
-            ai-code-c4-plantuml-output-relative-path)
+            (ai-code--topic-file-name ai-code-c4-plantuml-output-relative-path topic))
    "Use this Org structure:\n"
    "#+TITLE: C4 Architecture Overview\n\n"
    "* Purpose\n"
@@ -196,8 +335,10 @@ Default value is English."
    "* Source Evidence\n"
    "Provide a table mapping important claims to Org links pointing at source evidence."))
 
-(defun ai-code--derive-repo-map-prompt (git-root)
-  "Build and return a repository map derivation prompt for GIT-ROOT."
+(defun ai-code--derive-repo-map-prompt (git-root &optional topic link-style)
+  "Build and return a repository map derivation prompt for GIT-ROOT.
+TOPIC narrows the output file name when non-nil, and LINK-STYLE
+selects how code references are linked."
   (concat
    "Derive a lightweight Repository Map document for this existing repository.\n"
    "The primary goal is to help a new human contributor or AI coding agent quickly understand how to read and navigate the codebase.\n"
@@ -208,12 +349,12 @@ Default value is English."
    "Mark uncertainty explicitly when a file or directory purpose is inferred rather than documented.\n"
    "Prefer practical guidance over abstract architecture theory.\n"
    "Keep the document concise enough to be reused in future AI coding prompts.\n"
-   "When referencing any code file, folder, module, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description_text]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory).\n"
+   (ai-code--org-link-instruction ai-code-repo-map-output-relative-path link-style)
    "Use text and tables as the main format. Include at most two small PlantUML diagrams only when they improve navigation: one top-level dependency or module graph, and optionally one suggested reading-path graph.\n"
    "Use Org Babel PlantUML blocks with :file when adding diagrams.\n"
    (format "Repository root: %s\n" git-root)
    (format "Create or update the Org file at %s.\n\n"
-           ai-code-repo-map-output-relative-path)
+           (ai-code--topic-file-name ai-code-repo-map-output-relative-path topic))
    "Use this Org structure:\n"
    "#+TITLE: Repository Map\n\n"
    "* Purpose\n"
@@ -243,22 +384,27 @@ Default value is English."
    "* Source Evidence\n"
    "Provide a table mapping important claims to Org links pointing at source evidence."))
 
-(defun ai-code--architecture-guardrails-relative-path ()
-  "Return the repo-relative path for the architecture guardrails file."
+(defun ai-code--architecture-guardrails-relative-path (&optional topic)
+  "Return the repo-relative path for the architecture guardrails file.
+TOPIC narrows the file name when non-nil."
   (concat ai-code-files-dir-name "/"
           ai-code-file--architecture-guardrails-directory-name "/"
-          ai-code-file--architecture-guardrails-file-name))
+          (ai-code--topic-file-name
+           ai-code-file--architecture-guardrails-file-name topic)))
 
-(defun ai-code--architecture-guardrails-file-path ()
-  "Return the absolute path for the architecture guardrails file."
-  (expand-file-name ai-code-file--architecture-guardrails-file-name
+(defun ai-code--architecture-guardrails-file-path (&optional topic)
+  "Return the absolute path for the architecture guardrails file.
+TOPIC narrows the file name when non-nil."
+  (expand-file-name (ai-code--topic-file-name
+                     ai-code-file--architecture-guardrails-file-name topic)
                     (expand-file-name
                      ai-code-file--architecture-guardrails-directory-name
                      (ai-code--ensure-files-directory))))
 
-(defun ai-code--ensure-architecture-guardrails-file ()
-  "Create the architecture guardrails file with a starter template if missing."
-  (let ((target-file (ai-code--architecture-guardrails-file-path)))
+(defun ai-code--ensure-architecture-guardrails-file (&optional topic)
+  "Create the architecture guardrails file with a starter template if missing.
+TOPIC narrows the file name when non-nil."
+  (let ((target-file (ai-code--architecture-guardrails-file-path topic)))
     (unless (file-directory-p (file-name-directory target-file))
       (make-directory (file-name-directory target-file) t))
     (unless (file-exists-p target-file)
@@ -266,9 +412,11 @@ Default value is English."
         (insert ai-code-file--architecture-guardrails-template)))
     target-file))
 
-(defun ai-code--build-architecture-guardrails-prompt (git-root)
-  "Build the default prompt to derive architecture guardrails for GIT-ROOT."
-  (let ((relative-path (ai-code--architecture-guardrails-relative-path)))
+(defun ai-code--build-architecture-guardrails-prompt (git-root &optional topic link-style)
+  "Build the default prompt to derive architecture guardrails for GIT-ROOT.
+TOPIC narrows the output file name when non-nil, and LINK-STYLE
+selects how code references are linked."
+  (let ((relative-path (ai-code--architecture-guardrails-relative-path topic)))
     (mapconcat
      #'identity
      (list "Derive a lightweight architecture guardrails document for this existing repository."
@@ -283,7 +431,7 @@ Default value is English."
            "Focus on what helps future AI coding sessions avoid breaking boundaries or introducing messy dependencies."
            "Do not suggest large refactors unless clearly separated as optional future ideas."
            "Keep it concise, practical, and small enough to reuse in future AI prompts."
-           "When referencing any code file, folder, module, function, variable, or type, you MUST provide a relative Org-mode link in the format [[file:../../path/to/file::symbol_or_line][description]] pointing to its definition in the codebase (relative to the .ai.code.files/architecture/ output directory)."
+           (string-trim-right (ai-code--org-link-instruction relative-path link-style))
            ""
            "Use this Org structure:"
            "#+TITLE: Architecture Guardrails"
@@ -306,14 +454,17 @@ Default value is English."
   (let ((git-root (ai-code--git-root)))
     (unless git-root
       (user-error "Not in a git repository"))
-    (ai-code--ensure-architecture-guardrails-file)
-    (let* ((base-prompt (ai-code--build-architecture-guardrails-prompt git-root))
-           (initial-prompt (ai-code--append-document-language base-prompt)))
+    (let* ((topic (ai-code--read-document-topic))
+           (link-style (ai-code--read-document-link-style))
+           (base-prompt (ai-code--build-architecture-guardrails-prompt
+                         git-root topic link-style))
+           (initial-prompt (ai-code--finalize-document-prompt base-prompt topic)))
+      (ai-code--ensure-architecture-guardrails-file topic)
       (if-let ((final-prompt
                 (ai-code-plain-read-string "Prompt: " initial-prompt)))
           (progn
-            (ai-code--insert-prompt final-prompt)
-            (message "Requested architecture guardrails for %s" git-root))
+            (ai-code--doc-emit-prompt "Derive Architecture Guardrails" final-prompt)
+            (message "Architecture guardrails prompt ready for %s" git-root))
         (message "Architecture guardrails request cancelled")))))
 
 ;;;###autoload
@@ -323,16 +474,19 @@ The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository"))))
-    (ai-code--ensure-architecture-document-file "domain-context.org")
+                       (user-error "Not inside a Git repository")))
+         (topic (ai-code--read-document-topic))
+         (link-style (ai-code--read-document-link-style)))
+    (ai-code--ensure-architecture-document-file
+     (ai-code--topic-file-name "domain-context.org" topic))
     (let* ((base-prompt
-            (concat (ai-code--derive-ddd-context-prompt git-root)
+            (concat (ai-code--derive-ddd-context-prompt git-root topic link-style)
                     (or (ai-code--format-repo-context-info) "")))
-           (initial-prompt (ai-code--append-document-language base-prompt))
+           (initial-prompt (ai-code--finalize-document-prompt base-prompt topic))
            (final-prompt (ai-code-plain-read-string "Derive DDD context prompt: "
                                                     initial-prompt)))
       (when final-prompt
-        (ai-code--insert-prompt final-prompt)))))
+        (ai-code--doc-emit-prompt "Derive DDD Context for Repo" final-prompt)))))
 
 ;;;###autoload
 (defun ai-code-derive-test-context ()
@@ -341,16 +495,19 @@ The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository"))))
-    (ai-code--ensure-architecture-document-file "test-context.org")
+                       (user-error "Not inside a Git repository")))
+         (topic (ai-code--read-document-topic))
+         (link-style (ai-code--read-document-link-style)))
+    (ai-code--ensure-architecture-document-file
+     (ai-code--topic-file-name "test-context.org" topic))
     (let* ((base-prompt
-            (concat (ai-code--derive-test-context-prompt git-root)
+            (concat (ai-code--derive-test-context-prompt git-root topic link-style)
                     (or (ai-code--format-repo-context-info) "")))
-           (initial-prompt (ai-code--append-document-language base-prompt))
+           (initial-prompt (ai-code--finalize-document-prompt base-prompt topic))
            (final-prompt (ai-code-plain-read-string "Derive Test Context prompt: "
                                                     initial-prompt)))
       (when final-prompt
-        (ai-code--insert-prompt final-prompt)))))
+        (ai-code--doc-emit-prompt "Derive Test Context Document" final-prompt)))))
 
 ;;;###autoload
 (defun ai-code-derive-c4-plantuml ()
@@ -359,16 +516,20 @@ The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository"))))
-    (ai-code--ensure-architecture-document-file "c4-overview.org")
+                       (user-error "Not inside a Git repository")))
+         (topic (ai-code--read-document-topic))
+         (link-style (ai-code--read-document-link-style)))
+    (ai-code--ensure-architecture-document-file
+     (ai-code--topic-file-name "c4-overview.org" topic))
     (let* ((base-prompt
-            (concat (ai-code--derive-c4-plantuml-prompt git-root)
+            (concat (ai-code--derive-c4-plantuml-prompt git-root topic link-style)
                     (or (ai-code--format-repo-context-info) "")))
-           (initial-prompt (ai-code--append-document-language base-prompt))
+           (initial-prompt (ai-code--finalize-document-prompt base-prompt topic))
            (final-prompt (ai-code-plain-read-string "Derive C4 PlantUML prompt: "
                                                     initial-prompt)))
       (when final-prompt
-        (ai-code--insert-prompt final-prompt)))))
+        (ai-code--doc-emit-prompt "Derive C4 PlantUML Architecture Document"
+                                  final-prompt)))))
 
 ;;;###autoload
 (defun ai-code-derive-repo-map ()
@@ -377,16 +538,19 @@ The target Org file under `.ai.code.files/architecture/' is created if it does
 not already exist, so the backend has a concrete document to create or update."
   (interactive)
   (let* ((git-root (or (ai-code--git-root)
-                       (user-error "Not inside a Git repository"))))
-    (ai-code--ensure-architecture-document-file "repo-map.org")
+                       (user-error "Not inside a Git repository")))
+         (topic (ai-code--read-document-topic))
+         (link-style (ai-code--read-document-link-style)))
+    (ai-code--ensure-architecture-document-file
+     (ai-code--topic-file-name "repo-map.org" topic))
     (let* ((base-prompt
-            (concat (ai-code--derive-repo-map-prompt git-root)
+            (concat (ai-code--derive-repo-map-prompt git-root topic link-style)
                     (or (ai-code--format-repo-context-info) "")))
-           (initial-prompt (ai-code--append-document-language base-prompt))
+           (initial-prompt (ai-code--finalize-document-prompt base-prompt topic))
            (final-prompt (ai-code-plain-read-string "Derive repository map prompt: "
                                                     initial-prompt)))
       (when final-prompt
-        (ai-code--insert-prompt final-prompt)))))
+        (ai-code--doc-emit-prompt "Derive Repository Map" final-prompt)))))
 
 (provide 'ai-code-doc)
 ;;; ai-code-doc.el ends here
diff --git a/ai-code-github.el b/ai-code-github.el
index 0ca563c6..224b0149 100644
--- a/ai-code-github.el
+++ b/ai-code-github.el
@@ -444,17 +444,26 @@ ARG is the optional prefix argument to force including context."
   "Get Git repository web URL from git remote.
 Returns the HTTPS URL of the repository for web browsing.
 Supports GitHub, GitLab, Bitbucket, and other Git hosting services.
+Accepts HTTPS, SCP-style SSH, and ssh:// remotes, including SSH ports.
 Returns nil if unable to construct a web URL."
   (let* ((remote-url (magit-git-string "config" "--get" "remote.origin.url")))
     (when (and remote-url (stringp remote-url) (not (string-empty-p remote-url)))
       (cond
        ;; HTTPS URL: https://host.com/user/repo.git or https://host.com/user/repo
-       ((string-match "https://\\([^/]+\\)/\\(.+\\)" remote-url)
+       ((string-match "\\`https://\\([^/]+\\)/\\(.+\\)\\'" remote-url)
         (let ((host (match-string 1 remote-url))
               (path (match-string 2 remote-url)))
           (format "https://%s/%s" host (replace-regexp-in-string "\\.git$" "" path))))
-       ;; SSH URL: git@host.com:user/repo.git or git@host.com:user/repo
-       ((string-match "git@\\([^:]+\\):\\(.+\\)" remote-url)
+       ;; SSH URI: ssh://git@host.com[:port]/user/repo.git
+       ;; An SSH transport port is not the web server's HTTPS port.
+       ((string-match
+         "\\`ssh://\\(?:[^/@]+@\\)?\\([^/:]+\\)\\(?::[0-9]+\\)?/\\(.+\\)\\'"
+         remote-url)
+        (let ((host (match-string 1 remote-url))
+              (path (match-string 2 remote-url)))
+          (format "https://%s/%s" host (replace-regexp-in-string "\\.git$" "" path))))
+       ;; SCP-style SSH: git@host.com:user/repo.git
+       ((string-match "\\`git@\\([^/:]+\\):\\(.+\\)\\'" remote-url)
         (let ((host (match-string 1 remote-url))
               (path (match-string 2 remote-url)))
           (format "https://%s/%s" host (replace-regexp-in-string "\\.git$" "" path))))
@@ -509,4 +518,4 @@ Provide overall assessment.
 
 (provide 'ai-code-github)
 
-;;; ai-code-github.el ends here
\ No newline at end of file
+;;; ai-code-github.el ends here
diff --git a/test/test_ai-code-backends-infra.el b/test/test_ai-code-backends-infra.el
index 71536aa7..25bd1642 100644
--- a/test/test_ai-code-backends-infra.el
+++ b/test/test_ai-code-backends-infra.el
@@ -138,6 +138,13 @@ The result is a cons of whether SYMBOL is bound and its default value."
       (set-default symbol (cdr state))
     (makunbound symbol)))
 
+(defun test-ai-code-backends-infra--session-dir (directory)
+  "Return DIRECTORY the way session bookkeeping stores it.
+Session keys are canonicalized with `file-truename', so a key built from a
+literal path has to be resolved the same way to match.  This matters where
+the platform makes the literal path a symlink, such as /tmp on macOS."
+  (file-name-as-directory (file-truename directory)))
+
 (ert-deftest test-ai-code-backends-infra-output-meaningful-p-noise ()
   "Ensure terminal noise is not considered meaningful output."
   (should-not (ai-code-backends-infra--output-meaningful-p nil))
@@ -2059,7 +2066,9 @@ The prefix argument should also force instance-name prompting."
            nil
            "echo hi")
           (should (eq captured-table ai-code-backends-infra--processes))
-          (should (eq (gethash (cons working-dir "default")
+          (should (eq (gethash (cons (test-ai-code-backends-infra--session-dir
+                                     working-dir)
+                                    "default")
                                ai-code-backends-infra--processes)
                       'mock-process)))
        (when (buffer-live-p buffer)
@@ -2075,7 +2084,9 @@ The prefix argument should also force instance-name prompting."
          (cleanup-count 0))
     (unwind-protect
         (progn
-          (puthash (cons working-dir "default") process process-table)
+          (puthash (cons (test-ai-code-backends-infra--session-dir working-dir)
+                         "default")
+                   process process-table)
           (cl-letf (((symbol-function 'process-live-p)
                      (lambda (candidate) (eq candidate process)))
                     ((symbol-function 'ai-code-backends-infra--reuse-existing-session)
@@ -2355,7 +2366,8 @@ The prefix argument should also force instance-name prompting."
       (should (equal (plist-get context :buffer-name)
                      "*codex[ai-code-session-target:review]*"))
       (should (equal (plist-get context :session-key)
-                     (cons working-dir "review")))
+                     (cons (test-ai-code-backends-infra--session-dir working-dir)
+                           "review")))
       (should-not prompt-called))))
 
 (ert-deftest test-ai-code-backends-infra-resolve-session-target-does-not-prefill-prompt-buffer-filename ()
@@ -2398,7 +2410,8 @@ The prefix argument should also force instance-name prompting."
     (should (equal (plist-get context :buffer-name)
                    "*codex[ai-code-session-target:manual-session]*"))
     (should (equal (plist-get context :session-key)
-                   (cons working-dir "manual-session")))))
+                   (cons (test-ai-code-backends-infra--session-dir working-dir)
+                         "manual-session")))))
 
 (ert-deftest test-ai-code-backends-infra-resolve-session-target-prefills-source-buffer-branch ()
   "Source buffers should seed new instance names from the current branch."
@@ -2463,7 +2476,8 @@ The prefix argument should also force instance-name prompting."
     (should (equal (plist-get context :buffer-name)
                    "*codex[ai-code-session-target:feat/first-session]*"))
     (should (equal (plist-get context :session-key)
-                   (cons working-dir "feat/first-session")))))
+                   (cons (test-ai-code-backends-infra--session-dir working-dir)
+                         "feat/first-session")))))
 
 (ert-deftest test-ai-code-backends-infra-resolve-session-target-sanitizes-branch-name ()
   "Branch-derived instance names should keep session buffer names parseable."
@@ -2518,7 +2532,8 @@ The prefix argument should also force instance-name prompting."
     (should (equal (plist-get context :buffer-name)
                    "*codex[ai-code-session-target]*"))
     (should (equal (plist-get context :session-key)
-                   (cons working-dir "default")))))
+                   (cons (test-ai-code-backends-infra--session-dir working-dir)
+                         "default")))))
 
 (ert-deftest test-ai-code-backends-infra-resolve-session-context-includes-runtime-state ()
   "Resolved session context should include target data plus buffer and process."
@@ -2530,7 +2545,9 @@ The prefix argument should also force instance-name prompting."
          (context nil))
     (unwind-protect
         (progn
-          (puthash (cons working-dir "default") process process-table)
+          (puthash (cons (test-ai-code-backends-infra--session-dir working-dir)
+                         "default")
+                   process process-table)
           (setq context
                 (ai-code-backends-infra--resolve-session-context
                  working-dir
@@ -2542,7 +2559,9 @@ The prefix argument should also force instance-name prompting."
           (should (equal (plist-get context :instance-name) "default"))
           (should (equal (plist-get context :buffer-name) buffer-name))
           (should (equal (plist-get context :session-key)
-                         (cons working-dir "default")))
+                         (cons (test-ai-code-backends-infra--session-dir
+                                working-dir)
+                               "default")))
           (should (eq (plist-get context :buffer) buffer))
           (should (eq (plist-get context :existing-process) process)))
       (when (buffer-live-p buffer)
diff --git a/test/test_ai-code-doc.el b/test/test_ai-code-doc.el
index c39360ce..944dbc2c 100644
--- a/test/test_ai-code-doc.el
+++ b/test/test_ai-code-doc.el
@@ -25,7 +25,7 @@
 (require 'ai-code)
 
 (defmacro ai-code-file-with-test-env (&rest body)
-  "Set up a temporary environment for testing file operations.
+  "Run BODY in a temporary environment for testing file operations.
 This macro creates a temporary directory structure and ensures
 everything is cleaned up afterward."
   `(let* ((test-dir (expand-file-name "test-file-ops/" temporary-file-directory))
@@ -40,6 +40,12 @@ everything is cleaned up afterward."
        (when (file-directory-p test-dir)
          (delete-directory test-dir t)))))
 
+(defun ai-code-test--doc-read-string (topic language)
+  "Return a `read-string' stand-in answering TOPIC and LANGUAGE.
+The document topic question is recognized by its prompt prefix."
+  (lambda (prompt &rest _args)
+    (if (string-prefix-p "Document topic" prompt) topic language)))
+
 (ert-deftest ai-code-test-menu-agile-development-includes-derive-architecture-document-entry ()
   "Test that Agile Development menu exposes architecture document derivation."
   (let ((suffix (transient-get-suffix 'ai-code--menu-agile-development "A")))
@@ -102,7 +108,7 @@ everything is cleaned up afterward."
                    (lambda (&optional _dir)
                      tmp-root))
                   ((symbol-function 'read-string)
-                   (lambda (&rest _args) "English"))
+                   (ai-code-test--doc-read-string "" "English"))
                   ((symbol-function 'ai-code-plain-read-string)
                    (lambda (prompt initial-input)
                      (should (equal prompt "Prompt: "))
@@ -133,7 +139,7 @@ everything is cleaned up afterward."
                                   captured-initial-prompt))
           (should (string-match-p (regexp-quote "Org-mode format")
                                   captured-initial-prompt))
-          (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol_or_line][description]]")
+          (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol][description]]")
                                   captured-initial-prompt))
           (should (equal captured-final-prompt captured-initial-prompt)))
       (ignore-errors (delete-directory tmp-root t)))))
@@ -152,7 +158,7 @@ everything is cleaned up afterward."
                      (lambda (&optional _dir)
                        tmp-root))
                     ((symbol-function 'read-string)
-                     (lambda (&rest _args) "English"))
+                     (ai-code-test--doc-read-string "" "English"))
                     ((symbol-function 'ai-code-plain-read-string)
                      (lambda (_prompt initial-input)
                        initial-input))
@@ -182,7 +188,7 @@ everything is cleaned up afterward."
                    (lambda (&optional _dir)
                      tmp-root))
                   ((symbol-function 'read-string)
-                   (lambda (&rest _args) "English"))
+                   (ai-code-test--doc-read-string "" "English"))
                   ((symbol-function 'ai-code-plain-read-string)
                    (lambda (_prompt _initial-input)
                      nil))
@@ -209,7 +215,7 @@ everything is cleaned up afterward."
                 (lambda (&optional _dir)
                   default-directory))
                ((symbol-function 'read-string)
-                (lambda (&rest _args) "English"))
+                (ai-code-test--doc-read-string "" "English"))
                ((symbol-function 'ai-code-plain-read-string)
                 (lambda (prompt &optional initial-input)
                   (setq captured-read-prompt prompt
@@ -226,9 +232,11 @@ everything is cleaned up afterward."
        (should (string-match-p
                 "\\.ai\\.code\\.files/architecture/domain-context\\.org"
                 captured-initial-prompt))
+       (should-not (string-match-p "Scope this document to the topic"
+                                   captured-initial-prompt))
        (should (string-match-p "\\*\\* Notes and Uncertainties"
                                captured-initial-prompt))
-       (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol_or_line][description_text]]")
+       (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol][description]]")
                                captured-initial-prompt))
        (should (equal inserted-prompt captured-initial-prompt))
        (should (file-exists-p
@@ -243,7 +251,7 @@ everything is cleaned up afterward."
                 (lambda (&optional _dir)
                   default-directory))
                ((symbol-function 'read-string)
-                (lambda (&rest _args) "English"))
+                (ai-code-test--doc-read-string "" "English"))
                ((symbol-function 'ai-code--format-repo-context-info)
                 (lambda ()
                   "\nStored repository context:\n  - Preserve existing CLI UX"))
@@ -275,7 +283,7 @@ everything is cleaned up afterward."
                 (lambda (&optional _dir)
                   default-directory))
                ((symbol-function 'read-string)
-                (lambda (&rest _args) "English"))
+                (ai-code-test--doc-read-string "" "English"))
                ((symbol-function 'ai-code-plain-read-string)
                 (lambda (prompt &optional initial-input)
                   (setq captured-read-prompt prompt
@@ -292,7 +300,7 @@ everything is cleaned up afterward."
        (should (string-match-p
                 "\\.ai\\.code\\.files/architecture/test-context\\.org"
                 captured-initial-prompt))
-       (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol_or_line][description_text]]")
+       (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol][description]]")
                                captured-initial-prompt))
        (should (equal inserted-prompt captured-initial-prompt))
        (should (file-exists-p
@@ -311,9 +319,11 @@ everything is cleaned up afterward."
                    (lambda (&optional _dir) tmp-root))
                   ((symbol-function 'read-string)
                    (lambda (prompt &optional initial-input &rest _args)
-                     (setq captured-language-prompt prompt
-                           captured-language-default initial-input)
-                     mock-lang))
+                     (if (string-prefix-p "Document topic" prompt)
+                         ""
+                       (setq captured-language-prompt prompt
+                             captured-language-default initial-input)
+                       mock-lang)))
                   ((symbol-function 'ai-code-plain-read-string)
                    (lambda (_prompt initial-input) initial-input))
                   ((symbol-function 'ai-code--insert-prompt)
@@ -336,9 +346,11 @@ everything is cleaned up afterward."
                 (lambda (&optional _dir) default-directory))
                ((symbol-function 'read-string)
                 (lambda (prompt &optional initial-input &rest _args)
-                  (setq captured-language-prompt prompt
-                        captured-language-default initial-input)
-                  mock-lang))
+                  (if (string-prefix-p "Document topic" prompt)
+                      ""
+                    (setq captured-language-prompt prompt
+                          captured-language-default initial-input)
+                    mock-lang)))
                ((symbol-function 'ai-code-plain-read-string)
                 (lambda (_prompt initial-input) initial-input))
                ((symbol-function 'ai-code--insert-prompt)
@@ -360,9 +372,11 @@ everything is cleaned up afterward."
                 (lambda (&optional _dir) default-directory))
                ((symbol-function 'read-string)
                 (lambda (prompt &optional initial-input &rest _args)
-                  (setq captured-language-prompt prompt
-                        captured-language-default initial-input)
-                  mock-lang))
+                  (if (string-prefix-p "Document topic" prompt)
+                      ""
+                    (setq captured-language-prompt prompt
+                          captured-language-default initial-input)
+                    mock-lang)))
                ((symbol-function 'ai-code-plain-read-string)
                 (lambda (_prompt initial-input) initial-input))
                ((symbol-function 'ai-code--insert-prompt)
@@ -373,6 +387,241 @@ everything is cleaned up afterward."
        (should (string-match-p (regexp-quote "Generate the document in German.")
                                captured-final-prompt))))))
 
+(ert-deftest ai-code-test-derive-ddd-context-inserts-into-prompt-mode-buffer ()
+  "In `ai-code-prompt-mode' the DDD prompt is written at point instead of sent."
+  (ai-code-file-with-test-env
+   (let (sent-prompt)
+     (cl-letf (((symbol-function 'ai-code--git-root)
+                (lambda (&optional _dir) default-directory))
+               ((symbol-function 'read-string)
+                (ai-code-test--doc-read-string "" "English"))
+               ((symbol-function 'ai-code-plain-read-string)
+                (lambda (_prompt &optional initial-input) initial-input))
+               ((symbol-function 'ai-code--insert-prompt)
+                (lambda (prompt) (setq sent-prompt prompt))))
+       (with-temp-buffer
+         (ai-code-prompt-mode)
+         (insert "* Existing task\n** Sub task\n")
+         (goto-char (point-max))
+         (ai-code-derive-ddd-context)
+         (should-not sent-prompt)
+         (should (string-match-p "^\\*\\* Derive DDD Context for Repo \\["
+                                 (buffer-string)))
+         (should (string-match-p
+                  (regexp-quote "Domain-Driven Design (DDD) style context document")
+                  (buffer-string))))))))
+
+(ert-deftest ai-code-test-derive-architecture-guardrails-inserts-into-prompt-mode-buffer ()
+  "In `ai-code-prompt-mode' the guardrails prompt is written at point, not sent."
+  (ai-code-file-with-test-env
+   (let (sent-prompt)
+     (cl-letf (((symbol-function 'ai-code--git-root)
+                (lambda (&optional _dir) default-directory))
+               ((symbol-function 'read-string)
+                (ai-code-test--doc-read-string "" "English"))
+               ((symbol-function 'ai-code-plain-read-string)
+                (lambda (_prompt initial-input) initial-input))
+               ((symbol-function 'ai-code--insert-prompt)
+                (lambda (prompt) (setq sent-prompt prompt))))
+       (with-temp-buffer
+         (ai-code-prompt-mode)
+         (insert "* Existing task\n")
+         (goto-char (point-max))
+         (ai-code-derive-architecture-guardrails)
+         (should-not sent-prompt)
+         (should (string-match-p "^\\* Derive Architecture Guardrails \\["
+                                 (buffer-string)))
+         (should (string-match-p
+                  (regexp-quote "Derive a lightweight architecture guardrails document")
+                  (buffer-string))))))))
+
+(ert-deftest ai-code-test-derive-ddd-context-scopes-to-topic ()
+  "A non-empty document topic narrows the DDD prompt and its output file."
+  (ai-code-file-with-test-env
+   (let (captured-topic-prompt
+         inserted-prompt)
+     (cl-letf (((symbol-function 'ai-code--git-root)
+                (lambda (&optional _dir) default-directory))
+               ((symbol-function 'read-string)
+                (lambda (prompt &rest _args)
+                  (cond ((string-prefix-p "Document topic" prompt)
+                         (setq captured-topic-prompt prompt)
+                         "Prompt Pipeline")
+                        (t "English"))))
+               ((symbol-function 'ai-code-plain-read-string)
+                (lambda (_prompt &optional initial-input) initial-input))
+               ((symbol-function 'ai-code--insert-prompt)
+                (lambda (prompt) (setq inserted-prompt prompt))))
+       (ai-code-derive-ddd-context)
+       (should (equal captured-topic-prompt
+                      "Document topic (empty for whole repo): "))
+       (should (string-match-p
+                (regexp-quote "Scope this document to the topic: Prompt Pipeline")
+                inserted-prompt))
+       (should (string-match-p
+                (regexp-quote ".ai.code.files/architecture/domain-context-prompt-pipeline-13b070827c7b.org")
+                inserted-prompt))
+       (should (file-exists-p
+                (expand-file-name
+                 ".ai.code.files/architecture/domain-context-prompt-pipeline-13b070827c7b.org"
+                 default-directory)))))))
+
+(ert-deftest ai-code-test-derive-architecture-guardrails-scopes-to-topic ()
+  "A non-empty document topic narrows the guardrails prompt and its output file."
+  (ai-code-file-with-test-env
+   (let (inserted-prompt)
+     (cl-letf (((symbol-function 'ai-code--git-root)
+                (lambda (&optional _dir) default-directory))
+               ((symbol-function 'read-string)
+                (ai-code-test--doc-read-string "Git Integration" "English"))
+               ((symbol-function 'ai-code-plain-read-string)
+                (lambda (_prompt initial-input) initial-input))
+               ((symbol-function 'ai-code--insert-prompt)
+                (lambda (prompt) (setq inserted-prompt prompt))))
+       (ai-code-derive-architecture-guardrails)
+       (should (string-match-p
+                (regexp-quote "Scope this document to the topic: Git Integration")
+                inserted-prompt))
+       (should (string-match-p
+                (regexp-quote "@.ai.code.files/architecture/guardrails-git-integration-cd172722a457.org")
+                inserted-prompt))
+       (should (file-exists-p
+                (expand-file-name
+                 ".ai.code.files/architecture/guardrails-git-integration-cd172722a457.org"
+                 default-directory)))))))
+
+(ert-deftest ai-code-test-document-prompts-require-verified-org-links ()
+  "Every derived document prompt asks for verified relative Org links."
+  (dolist (builder '(ai-code--derive-ddd-context-prompt
+                     ai-code--derive-test-context-prompt
+                     ai-code--derive-c4-plantuml-prompt
+                     ai-code--derive-repo-map-prompt
+                     ai-code--build-architecture-guardrails-prompt))
+    (let ((prompt (funcall builder "/tmp/repo")))
+      (should (string-match-p
+               (regexp-quote "[[file:../../path/to/file::symbol][description]]")
+               prompt))
+      (should (string-match-p
+               (regexp-quote "fall back to ::<line-number> only when")
+               prompt))
+      (should (string-match-p
+               (regexp-quote "Only link to paths and symbols you have actually confirmed")
+               prompt))
+      (should (string-match-p (regexp-quote "first mention in each section")
+                              prompt)))))
+
+(ert-deftest ai-code-test-org-link-instruction-prefix-follows-output-depth ()
+  "The relative link prefix is derived from the document output depth."
+  (should (string-match-p (regexp-quote "[[file:../../path/to/file::symbol]")
+                          (ai-code--org-link-instruction "a/b/doc.org")))
+  (should (string-match-p (regexp-quote "[[file:../path/to/file::symbol]")
+                          (ai-code--org-link-instruction "a/doc.org")))
+  (should (string-match-p (regexp-quote "[[file:path/to/file::symbol]")
+                          (ai-code--org-link-instruction "doc.org"))))
+
+(ert-deftest test-ai-code-doc--topic-file-name-distinguishes-lossy-slugs ()
+  "Distinct topics must not update the same output document."
+  (let* ((topics '("\u8ba4\u8bc1" "\u652f\u4ed8" "C++" "C#" "c#"))
+         (paths (mapcar (lambda (topic)
+                          (ai-code--topic-file-name "docs/domain-context.org"
+                                                    topic))
+                        topics)))
+    (should (= (length topics) (length (delete-dups (copy-sequence paths)))))
+    (dolist (path paths)
+      (should (equal (file-name-directory path) "docs/"))
+      (should (equal (file-name-extension path) "org")))
+    (should (equal (car paths)
+                   (ai-code--topic-file-name "docs/domain-context.org"
+                                             (car topics))))))
+
+(ert-deftest test-ai-code-doc--topic-file-name-preserves-repository-path ()
+  "Whole-repository documents retain their established output path."
+  (should (equal (ai-code--topic-file-name "docs/domain-context.org" nil)
+                 "docs/domain-context.org")))
+
+(ert-deftest test-ai-code-doc--github-links-follow-analyzed-revision ()
+  "Pin feature-branch links and use local links for unpublished or dirty code."
+  (let* ((repo (make-temp-file "ai-code-doc-git-" t))
+         (default-directory (file-name-as-directory repo))
+         (process-environment (append '("GIT_CONFIG_GLOBAL=/dev/null"
+                                        "GIT_CONFIG_NOSYSTEM=1")
+                                      process-environment)))
+    (unwind-protect
+        ;; Execute real Git queries even when other test files stub Magit.
+        (cl-letf (((symbol-function 'magit-git-string)
+                   (lambda (&rest args)
+                     (with-temp-buffer
+                       (when (zerop (apply #'process-file "git" nil t nil args))
+                         (car (split-string (buffer-string) "\n" t))))))
+                  ((symbol-function 'magit-git-success)
+                   (lambda (&rest args)
+                     (zerop (apply #'process-file "git" nil nil nil args)))))
+          (cl-labels ((git (&rest args)
+                        (should (zerop
+                                 (apply #'process-file "git" nil nil nil
+                                        "-c" "user.name=Document Test"
+                                        "-c" "user.email=doc@example.com"
+                                        "-c" "commit.gpgsign=false" args)))))
+            (git "init" "-q" "-b" "main")
+            (git "remote" "add" "origin" "ssh://git@github.com/org/repo.git")
+            ;; An unborn repository cannot supply a source revision.
+            (should-not (ai-code--doc-github-source-url))
+            (with-temp-file "source.txt" (insert "Main definition\n"))
+            (with-temp-file ".gitignore" (insert "generated.txt\n"))
+            (git "add" ".")
+            (git "commit" "-qm" "Initial source")
+            (git "update-ref" "refs/remotes/origin/main" "HEAD")
+            (git "checkout" "-qb" "feature")
+            (with-temp-file "source.txt" (insert "Feature definition\n"))
+            (git "commit" "-qam" "Feature source")
+            ;; A commit on another remote does not prove origin has it.
+            (git "update-ref" "refs/remotes/upstream/feature" "HEAD")
+            (should-not (ai-code--doc-github-source-url))
+            (cl-letf (((symbol-function 'read-string)
+                       (lambda (&rest _) (ert-fail "Unexpected link question"))))
+              (should (eq (ai-code--read-document-link-style) 'local)))
+            (git "update-ref" "refs/remotes/origin/feature" "HEAD")
+            (let* ((revision (magit-git-string "rev-parse" "HEAD"))
+                   (source-url (concat "https://github.com/org/repo/blob/"
+                                       revision)))
+              (should (equal (ai-code--doc-github-source-url) source-url))
+              (cl-letf (((symbol-function 'read-string)
+                         (lambda (&rest _) "github")))
+                (should (eq (ai-code--read-document-link-style) 'github)))
+              (let ((prompt (ai-code--org-link-instruction "a/b/doc.org" 'github)))
+                (should (string-match-p (regexp-quote (concat source-url "/"))
+                                        prompt))
+                (should-not (string-match-p "/blob/HEAD/" prompt))
+                (should (string-match-p "untracked, ignored" prompt)))
+              ;; New document files must not disable links to committed code.
+              (with-temp-file "doc.org" (insert "Draft document\n"))
+              (with-temp-file "generated.txt" (insert "Generated output\n"))
+              (should (equal (ai-code--doc-github-source-url) source-url))
+              (git "checkout" "--detach" "-q")
+              (should (equal (ai-code--doc-github-source-url) source-url))
+              ;; Both unstaged and staged edits invalidate committed line numbers.
+              (with-temp-file "source.txt" (insert "Local definition\n"))
+              (should-not (ai-code--doc-github-source-url))
+              (git "add" "source.txt")
+              (should-not (ai-code--doc-github-source-url))
+              (let ((prompt (ai-code--org-link-instruction "a/b/doc.org" 'github)))
+                (should-not (string-match-p "https://github.com" prompt))
+                (should (string-match-p
+                         (regexp-quote "[[file:../../path/to/file::symbol]")
+                         prompt))))))
+      (delete-directory repo t))))
+
+(ert-deftest test-ai-code-doc--github-source-url-handles-git-failure ()
+  "An unavailable Git command must leave local document links usable."
+  (cl-letf (((symbol-function 'ai-code--doc-github-repo-url)
+             (lambda () "https://github.com/org/repo"))
+            ((symbol-function 'magit-git-string)
+             (lambda (&rest _) (error "Git unavailable"))))
+    (should-not (ai-code--doc-github-source-url))
+    (should (string-match-p
+             (regexp-quote "[[file:path/to/file::symbol]")
+             (ai-code--org-link-instruction "doc.org" 'github)))))
+
 (provide 'test_ai-code-doc)
 ;;; test_ai-code-doc.el ends here
 ;;; test_ai-code-doc.el ends here
diff --git a/test/test_ai-code-editor-viewport.el b/test/test_ai-code-editor-viewport.el
index 618baf99..678ad199 100644
--- a/test/test_ai-code-editor-viewport.el
+++ b/test/test_ai-code-editor-viewport.el
@@ -62,10 +62,15 @@ Give the source side window WIDTH columns, defaulting to 40."
           :viewport-window (plist-get display-state :window))))
 
 (defun ai-code-editor-viewport-test--transpose-parent-if-supported (window)
-  "Transpose WINDOW's parent when the current Emacs provides `window-x'."
+  "Transpose WINDOW's parent when the current Emacs and layout allow it.
+`window-layout-transpose' needs `window-x', which only ships with newer
+Emacs versions, and it refuses layouts holding a dedicated, fixed size or
+atomic window, which side windows are.  Both cases only cost the caller
+the extra stress of a rearranged layout, so they are ignored here."
   (when (require 'window-x nil t)
     (let ((ignore-window-parameters t))
-      (window-layout-transpose (window-parent window)))))
+      (ignore-error user-error
+        (window-layout-transpose (window-parent window))))))
 
 (ert-deftest test-ai-code-editor-viewport--mode-uses-one-yank-key ()
   "Viewport users should paste every supported clipboard type with `C-y'."
diff --git a/test/test_ai-code-github.el b/test/test_ai-code-github.el
index 751f2e0c..597cd420 100644
--- a/test/test_ai-code-github.el
+++ b/test/test_ai-code-github.el
@@ -693,6 +693,24 @@ branch as the PR base."
     (should (string-match-p "Class definition: class GreetingService:" captured-prompt))
     (should (string-match-p "Function definition: defun hello-world ()" captured-prompt))))
 
+(ert-deftest test-ai-code-github--get-git-web-repo-url-supports-remote-formats ()
+  "Normalize supported remotes without treating SSH ports as path segments."
+  (dolist (entry '(("https://github.com/org/repo.git" . "https://github.com/org/repo")
+                   ("https://gitlab.example:8443/org/repo" . "https://gitlab.example:8443/org/repo")
+                   ("git@github.com:org/repo.git" . "https://github.com/org/repo")
+                   ("ssh://git@github.com/org/repo.git" . "https://github.com/org/repo")
+                   ("ssh://git@github.com:22/org/repo.git" . "https://github.com/org/repo")
+                   ("ssh://github.com/org/repo" . "https://github.com/org/repo")
+                   ("ssh://git@gitlab.example:2222/group/repo.git" . "https://gitlab.example/group/repo")
+                   ("ssh://git@github.com:invalid/org/repo.git" . nil)
+                   ("/tmp/git@github.com:org/repo.git" . nil)
+                   ("/tmp/https://github.com/org/repo.git" . nil)
+                   ("" . nil)
+                   (nil . nil)))
+    (cl-letf (((symbol-function 'magit-git-string)
+               (lambda (&rest _) (car entry))))
+      (should (equal (ai-code--get-git-web-repo-url) (cdr entry))))))
+
 (provide 'test_ai-code-github)
 
 ;;; test_ai-code-github.el ends here
diff --git a/test/test_ai-code-harness.el b/test/test_ai-code-harness.el
index 52209b04..0b629c84 100644
--- a/test/test_ai-code-harness.el
+++ b/test/test_ai-code-harness.el
@@ -43,6 +43,14 @@
                            "--eval" form)))
         (list exit-code (buffer-string))))))
 
+(defun ai-code-harness-test--error-reported-p (output)
+  "Return non-nil when OUTPUT contains an Emacs \"Error:\" report.
+The match is case sensitive on purpose: `case-fold-search' defaults to t
+in batch mode, so a case-insensitive search also matches lower-case
+\"error:\" text in platform noise the inferior Emacs writes to stderr."
+  (let ((case-fold-search nil))
+    (string-match-p "Error:" output)))
+
 (defun ai-code-harness-test--grill-context (origin-command)
   "Return a Grill prompt context for ORIGIN-COMMAND."
   (ai-code--make-prompt-context
@@ -76,7 +84,7 @@
           "'ai-code-code-change)) "
           "(kill-emacs 1)))"))))
     (should (equal exit-code 0))
-    (should-not (string-match-p "Error:" output))))
+    (should-not (ai-code-harness-test--error-reported-p output))))
 
 (ert-deftest ai-code-test-grill-autoloaded-entry-loads-harness ()
   "Loading an autoloaded entry module should install the Grill provider."
@@ -98,7 +106,7 @@
           "'ai-code-code-change)) "
           "(kill-emacs 1)))"))))
     (should (equal exit-code 0))
-    (should-not (string-match-p "Error:" output))))
+    (should-not (ai-code-harness-test--error-reported-p output))))
 
 (ert-deftest ai-code-test-grill-harness-reload-removes-legacy-prompt-advice ()
   "Reloading the harness should remove legacy Grill prompt advice."
diff --git a/test/test_ai-code-session.el b/test/test_ai-code-session.el
index 7b6652ac..6d16abf6 100644
--- a/test/test_ai-code-session.el
+++ b/test/test_ai-code-session.el
@@ -246,7 +246,9 @@
   "D should open Magit status setup for the session repository."
   (ai-code-test-session--with-clean-registry
    (let ((session-buffer (get-buffer-create "*codex[diff]*"))
-         (repo-root (make-temp-file "ai-code-dashboard-diff-" t))
+         ;; Resolve the temporary directory, because the dashboard reports the
+         ;; repository root canonicalized and /var is a symlink on macOS.
+         (repo-root (file-truename (make-temp-file "ai-code-dashboard-diff-" t)))
          dashboard-buffer
          opened-repo)
      (unwind-protect