feat(workspace-hub): polish backlog follow-through

Author: RichardGeorgeDavis

docs/CHANGELOG.md

@@ -6,6 +6,8 @@
 - Updated [HANDOVER](HANDOVER.md) completion review, the project review addendum pointer to [CHANGELOG](CHANGELOG.md) for resolved Hub items, and aligned [docs/README](README.md), wiki stubs, contributor templates, and [AGENTS.md](../AGENTS.md) with the same stance.
 - Rewrote [00-overview](00-overview.md) and [02-local-runtime-handover](02-local-runtime-handover.md) so runtime guidance uses generic mapped-host terminology while keeping stable manifest enum and field names (`servbay`, `servbayPath`, `servbaySubdomain`) documented in [repos/workspace-hub/docs/manifest.md](../repos/workspace-hub/docs/manifest.md).
 - Added a tracked [docs/plans/readme-docs-closeout.md](plans/readme-docs-closeout.md) plan for future reference, and aligned small Workspace Hub/operator copy surfaces with the same mapped-host wording in `repos/workspace-hub`, `tools/scripts/doctor-workspace.sh`, and `tools/scripts/setup-workspace-profile.sh`.
+- Extended `repos/workspace-hub` backlog follow-through with better repo-list prioritization for pinned and recent work, clearer Python-aware dependency readiness, intake-result surfacing in repo details, capability search and inspection, explicit mapped-host routing status, and richer runtime troubleshooting guidance.
+- Advanced Workspace memory graph support from file-open-only toward Phase 2 by surfacing derived-edge counts, node-type breakdown, and an in-app graph report preview for the selected target, while clarifying intentional MCP profile usage in the Workspace Hub settings panel.
 
 ## 2026-04-10
 

docs/HANDOVER.md

@@ -201,10 +201,9 @@ Status: complete and validated
 
 Current likely pickup:
 
-- apply the managed MCP v1 profiles on the machines that need them and use `safe-readonly` versus `default-full` intentionally rather than treating MCP as an always-on hidden dependency
-- `repos/workspace-hub` memory-graph Phase 2 only if operators need richer relationship extraction, filtering, or in-app embedding beyond the current file-open flow
-- `repos/workspace-hub` capability drill-down if operators need deeper per-capability install/update health than the current snapshot
-- `repos/workspace-hub` repo-intake polish if new repos still need clearer first-run notes, optional ability guidance, or tighter starter docs
+- apply the managed MCP v1 profiles on the machines that need them and keep `safe-readonly` versus `default-full` intentional rather than hidden defaults
+- extend cross-stack dependency detection beyond the current Node, Composer, and Python-local-environment heuristics if operators need deeper readiness checks
+- deepen Memory Graph beyond the current in-app report preview and node-type breakdown only if operators need richer relationship extraction or graph interaction
 - keep future batches end-to-end and update this file when a batch becomes the new practical pickup point
 
 ## Acceptance closeout (2026-04-10)
@@ -295,11 +294,9 @@ What appears complete or substantially complete:
 
 What still reads as open or incomplete in the docs:
 
-- deeper repo diagnostics and drill-down polish
-- favourites and last-opened polish
-- clearer dependency-readiness feedback
-- clearer mapped-host and proxy preview polish where operators use that workflow
-- additional runtime troubleshooting documentation
+- broader cross-stack dependency-readiness heuristics beyond the current Node, Composer, and Python-local-environment checks
+- deeper mapped-host preview generation and operator-specific routing automation beyond the current routing status and guidance
+- richer in-app graph exploration if operators need more than the current report preview and node-type breakdown
 
 ## Core memory decision (2026-04-08)
 

repos/workspace-hub/docs/memory-graph.md

@@ -171,9 +171,11 @@ Status: implemented
 
 ### Phase 2
 
-- enrich the adapter with conversation exports and wake-up summaries
-- add bridge-node and centrality summaries
-- support basic filtering by node type and confidence
+Status: partially implemented
+
+- graph snapshots now surface derived-edge counts and node-type breakdown in Workspace Hub
+- the Workspace memory page now shows an in-app preview of `graph-report.md` for the selected target
+- later work can still enrich the adapter with conversation exports, bridge-node or centrality summaries, and interactive filtering by node type or confidence
 
 ### Phase 3
 

repos/workspace-hub/docs/runtime-troubleshooting.md

@@ -20,6 +20,12 @@ If the repo has no inferred install command:
 2. Add `installCommand` to `.workspace/project.json` if the repo needs one.
 3. Re-run the install from Workspace Hub.
 
+If the repo looks like a Python-style project:
+
+1. Confirm whether it expects a local `.venv/` or `venv/`.
+2. If it does, create or refresh that environment before retrying the runtime.
+3. If it intentionally uses a global interpreter or another workflow, capture that in repo docs so the next operator does not misread the Hub warning.
+
 If the missing piece is not a repo dependency but an optional workspace ability:
 
 1. Do not hide that requirement in the repo manifest.
@@ -53,6 +59,12 @@ If Workspace Hub shows the repo as `running` but health is `unreachable`:
 3. Review the runtime log for the actual local URL.
 4. Save a `previewUrl` or `healthcheckUrl` override when the repo uses a fixed non-default address.
 
+If the repo prefers mapped-host routing:
+
+1. Confirm the repo has a stable mapped-host path or subdomain in the manifest.
+2. Save an explicit `previewUrl` once the routed hostname is known, instead of relying on transient runtime-log URLs.
+3. Check the operator’s reverse-proxy or local-host mapping outside Workspace Hub if the route is configured but still unreachable.
+
 If `Open preview` attempted to start the repo but still failed to open a working preview:
 
 1. Read the runtime log in the details panel first.
@@ -89,3 +101,11 @@ Practical response:
 Update `.workspace/project.json` when Workspace Hub keeps inferring the wrong command, package manager, preview URL, or preferred mode. Use saved overrides for temporary local corrections and the manifest for repo-native behaviour that should stay with the repo.
 
 Do not use the manifest to imply that an optional workspace ability is present. If a workflow depends on one, document that explicitly in repo docs and keep the install path visible to the next contributor.
+
+## Repo intake follow-up
+
+After running repo intake:
+
+1. Read the intake notes in the details panel before assuming the repo is fully ready.
+2. Check whether intake created a manifest or intentionally skipped it.
+3. Fill in any repo-specific install, dev, preview, or mapped-host details that conservative intake could not infer safely.

repos/workspace-hub/server/mempalace-graph.ts

@@ -37,7 +37,15 @@ export type MempalaceGraphArtifactPaths = {
 }
 
 type MempalaceGraphDocument = {
+  edges?: Array<{
+    confidence?: number
+    derived?: boolean
+    type?: string
+  }>
   generatedAt?: string
+  nodes?: Array<{
+    type?: string
+  }>
   summary?: {
     edgeCount?: number
     nodeCount?: number
@@ -47,11 +55,14 @@ type MempalaceGraphDocument = {
 export type MempalaceGraphSnapshot = {
   artifacts: MempalaceGraphArtifactPaths
   available: boolean
+  derivedEdgeCount: number | null
   edgeCount: number | null
   lastBuiltAt: string | null
   nodeCount: number | null
+  nodeTypeCounts: Partial<Record<string, number>>
   outputDirectory: string | null
   outputDirectoryExists: boolean
+  reportExcerpt: string[]
 }
 
 async function fileExists(targetPath: string) {
@@ -75,11 +86,14 @@ export async function readMempalaceGraphSnapshot(
         reportPath: null,
       },
       available: false,
+      derivedEdgeCount: null,
       edgeCount: null,
       lastBuiltAt: null,
       nodeCount: null,
+      nodeTypeCounts: {},
       outputDirectory: null,
       outputDirectoryExists: false,
+      reportExcerpt: [],
     }
   }
 
@@ -101,17 +115,46 @@ export async function readMempalaceGraphSnapshot(
     }
   }
 
+  let reportExcerpt: string[] = []
+  if (reportExists) {
+    try {
+      reportExcerpt = (await readFile(reportPath, 'utf8'))
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(0, 8)
+    } catch {
+      reportExcerpt = []
+    }
+  }
+
+  const nodeTypeCounts = Object.fromEntries(
+    Object.entries(
+      (document?.nodes ?? []).reduce<Record<string, number>>((counts, node) => {
+        const type = typeof node.type === 'string' && node.type.trim() ? node.type.trim() : 'unknown'
+        counts[type] = (counts[type] ?? 0) + 1
+        return counts
+      }, {}),
+    ).sort(([left], [right]) => left.localeCompare(right)),
+  )
+  const derivedEdgeCount = document
+    ? (document.edges ?? []).filter((edge) => edge.derived).length
+    : null
+
   return {
     artifacts: {
       htmlPath: htmlExists ? htmlPath : null,
       jsonPath: jsonExists ? jsonPath : null,
       reportPath: reportExists ? reportPath : null,
     },
     available: true,
+    derivedEdgeCount,
     edgeCount: typeof document?.summary?.edgeCount === 'number' ? document.summary.edgeCount : null,
     lastBuiltAt: document?.generatedAt ?? null,
     nodeCount: typeof document?.summary?.nodeCount === 'number' ? document.summary.nodeCount : null,
+    nodeTypeCounts,
     outputDirectory,
     outputDirectoryExists,
+    reportExcerpt,
   }
 }

repos/workspace-hub/server/workspace.ts

@@ -1338,10 +1338,17 @@ async function readDependencyState(options: {
   names: string[]
   packageManager: string
   previewCommand: string | null
+  type?: RepoType
 }): Promise<RepoDependencyState> {
   const normalizedPackageManager = options.packageManager.split('@')[0] ?? ''
   const hasPackageJson = options.names.includes('package.json')
   const hasComposerJson = options.names.includes('composer.json')
+  const hasPythonProject =
+    options.names.includes('pyproject.toml') ||
+    options.names.includes('requirements.txt') ||
+    options.names.includes('Pipfile') ||
+    options.names.includes('setup.py') ||
+    options.names.includes('uv.lock')
   const isNodeStyleRepo =
     hasPackageJson ||
     normalizedPackageManager === 'npm' ||
@@ -1406,6 +1413,38 @@ async function readDependencyState(options: {
     } satisfies RepoDependencyState
   }
 
+  if (hasPythonProject) {
+    const virtualEnvPaths = ['.venv', 'venv'].map((directoryName) =>
+      path.join(options.fullPath, directoryName),
+    )
+
+    for (const installPath of virtualEnvPaths) {
+      if (await fileExists(installPath)) {
+        return {
+          installPath,
+          reason: `${path.basename(installPath)}/ is present for this Python-style repo.`,
+          state: 'ready',
+        } satisfies RepoDependencyState
+      }
+    }
+
+    return {
+      installPath: virtualEnvPaths[0] ?? null,
+      reason:
+        'Python project markers were found, but no local virtual environment was detected. Confirm whether this repo expects .venv/, venv/, or a global interpreter workflow.',
+      state: options.installCommand ? 'missing' : 'unknown',
+    } satisfies RepoDependencyState
+  }
+
+  if (options.type === 'wordpress' && !options.installCommand && !hasComposerJson) {
+    return {
+      installPath: null,
+      reason:
+        'This WordPress repo usually relies on an external runtime, so repo-local dependency readiness is not treated as a blocker.',
+      state: 'not-applicable',
+    } satisfies RepoDependencyState
+  }
+
   if (options.installCommand) {
     return {
       installPath: null,
@@ -1784,6 +1823,15 @@ function isRepoCandidate(names: string[], collection: string | null) {
     return true
   }
 
+  if (
+    names.includes('pyproject.toml') ||
+    names.includes('requirements.txt') ||
+    names.includes('Pipfile') ||
+    names.includes('setup.py')
+  ) {
+    return true
+  }
+
   if (
     names.includes('index.html') ||
     names.includes('wp-config.php') ||
@@ -1920,6 +1968,7 @@ async function buildRepoRecord(
         names,
         packageManager,
         previewCommand,
+        type,
       }),
     ])