# Project Hub Scaffold

> Stand up a browsable HTML console over a folder of project documents — Project Hub is a zero-dependency Node server plus a static explorer that turns any workspace into a clickable document tree in the browser, with no build step and no install. Use when asked to add a workspace to an existing Project Hub, scaffold a fresh portable installation of the server and explorer, build a document browser or docs console for a project, or match an existing Hub page's theme, sidebar tree and navigation. Source: github.com/ai-automation-tools/project-hub (MIT).

- Skill: `ai-automation-tools/project-hub-scaffold` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add ai-automation-tools/project-hub-scaffold`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-automation-tools/project-hub-scaffold/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ai-automation-tools (https://skillmd.com/u/ai-automation-tools)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/ai-automation-tools/project-hub-scaffold

---


# Project Hub scaffold

Reuse an existing Project Hub engine: a local filesystem scanner and vanilla-JS
explorer. Find the checkout containing `Hub/hub.mjs` and `Hub/index.html` from the
user's context; ask for its location only if it cannot be found. Do not reconstruct
the engine from screenshots. Read its README and [config reference](references/config-schema.md).
The engine is the source of truth if this reference has drifted.

## Choose the mode

- **A — add a workspace (default).** Add `Projects/<Name>/hub.config.json` to the
  existing installation. One server scans all projects and shared roots. No new
  port, launcher, engine copy, or hub-switcher entry is needed.
- **B — portable installation.** Use when the project must carry its own engine.
  Copy the complete runtime and tests into `Hub/`, the launcher and example into
  `Project-Hub/`, and create `Projects/<Name>/`. Each machine supplies its own
  ignored configs. Independent copies need their own future engine updates.
- **C — visual match.** For an explicitly static page, read the
  [design system](references/design-system.md) and reuse the actual theme and
  layout from `Hub/index.html`. Explain that scanning, native launch actions,
  previews, and server-backed search require A or B.

## Workflow

1. Inspect the existing server config, project configs, and target folder. Preserve
   existing work. Project display names and folders must be unique; `dir` must
   exist. Choose either repo groups or a path prefix ending in `/`, or omit scope.
2. Run [scripts/scaffold-hub.ps1](scripts/scaffold-hub.ps1) for A or B. It refuses
   existing destinations. A writes only a project config. B copies an allowlist of
   engine files, license, launchers and examples; it never copies scan output,
   credentials, personal configs, screenshots, or design archives.
3. In B, select an available port and `base`; shared roots default to empty. Verify
   the configured port is free before starting. Roots come from configuration and
   user runtimes use the current home directory: do not edit source constants for
   machine paths. The runtime scans supported user-scope agent folders as well as
   configured roots; disclose that scope to the user.
4. Run `npm test` from `Hub/`. Fresh clones validate example shapes without needing
   personal configs; installed configs are checked when present. Separately check
   all configured directories exist. Tests do not prove a port is free or a page works.
5. New project configs are discovered at **startup**. Restart the existing server
   through `Project-Hub/Start-Hub.ps1 -Restart -NoBrowser` when authorized by the
   setup task, then check `/api/health` and `/api/scan`. Use the configured port.
   Never terminate a foreign process to claim a port.
6. Verify the Projects landing page, target workspace, sidebar, search, a rendered
   document, and Back/Forward in a browser. Use a temporary fixture installation
   for script validation; do not start a second scanner over real private roots.
7. Link the skill and setup instructions from the project's README. Keep personal
   roots, ports in instance inventories, and editor wiring in ignored local files.
   Scheduled tasks and workspace auto-start are optional integrations, not actions
   every scaffold should install. Public source publication is separate from
   exposing the local server over a network.

## Helper usage

PowerShell 7; use paths appropriate to the user's machine:

```powershell
# A: mount another workspace in the shared process
./scripts/scaffold-hub.ps1 -HubDesignRoot C:/Tools/ProjectHub `
  -Name Demo -Dir C:/Work/Projects/Demo -RepoScopePathPrefix Repos/

# B: new standalone installation (destination must not exist)
./scripts/scaffold-hub.ps1 -HubDesignRoot C:/Tools/ProjectHub `
  -Name Demo -Dir C:/Work/Projects/Demo -Standalone `
  -TargetDir C:/Tools/DemoHub -Base C:/Work -Port 4400
```

## Current behavior to preserve

Read [current features](references/current-features.md) when extending or checking
an installation. It covers the shared Projects landing page, lazy Pictures,
sandboxed HTML/PDF report reading, search and heading routes, bookmarks and Recent,
folder sorting, Markdown reader tools, help panels, and watchdog behavior.
Read the design reference only for UI work; adding a workspace needs no UI edit.

## Avoid

- Creating `Project-Hub-<Name>` and a separate server per workspace: that is the retired layout.
- Copying only `hub.mjs` and `index.html`: the runtime imports other modules.
- Hardcoding an owner's drive, user profile, scheduled-task name, or project list.
- Committing `hub.config.json`, `scan.json`, logs, or private design exports.
- Claiming current-file sanitization also removes Git history or hosted attachments.
- Claiming browser checks, native launches, or scheduled tasks passed without executing them.