Uselink onboarding

Onboarding Guide → Uselink

Scan a codebase, generate a comprehensive getting-started guide for new developers, and publish it to uselink as a shareable link.

When to Use

• "Create an onboarding guide for the new hire"
• "How do I explain this repo to someone new? Publish it."
• "Generate a getting-started doc and share it"
• "Make a dev setup guide I can send to contractors"

Prerequisites

which uselink || echo "MISSING"
test -f ~/.uselink/config.json && echo "OK" || echo "NO_CONFIG"

Workflow

1. Scan the codebase

# Project identity
git remote get-url origin 2>/dev/null
basename "$(git rev-parse --show-toplevel)"

# Build system
for f in Makefile package.json build.gradle.kts Cargo.toml go.mod pyproject.toml docker-compose.yml; do
  test -f "$f" && echo "BUILD: $f"
done

# Environment files
ls .env.example .env.sample .env.template 2>/dev/null
ls .tool-versions .node-version .java-version .python-version .ruby-version 2>/dev/null

# Documentation
ls README.md CLAUDE.md CONTRIBUTING.md docs/ .github/CONTRIBUTING.md 2>/dev/null

# Infrastructure
ls Dockerfile docker-compose.yml 2>/dev/null
ls .github/workflows/*.yml 2>/dev/null

# Directory structure
find . -maxdepth 2 -type d -not -path "*/.git*" -not -path "*/node_modules*" -not -path "*/build*" -not -path "*/__pycache__*" | sort

2. Read key files

Read (first 150 lines of each):

• README.md — existing setup instructions
• CLAUDE.md — architecture and conventions
• Makefile or equivalent — available commands
• .env.example — required environment variables
• docker-compose.yml — required services
• Main entry point file

3. Generate HTML

Write to /tmp/uselink-onboarding-<project>-<timestamp>.html.

Sections:

<!-- Welcome -->
<div class="card">
  <h3>Welcome to {{PROJECT}}</h3>
  <p>{{ONE_LINE_DESCRIPTION}}</p>
  <p class="muted">This guide will get you from zero to running the app locally.</p>
</div>

<!-- Prerequisites -->
<h2>Prerequisites</h2>
<div class="card">
  <table>
    <thead><tr><th>Tool</th><th>Version</th><th>Install</th></tr></thead>
    <tbody>
      <tr><td>{{TOOL}}</td><td>{{VERSION}}</td><td><code>{{INSTALL_CMD}}</code></td></tr>
    </tbody>
  </table>
</div>

<!-- Clone & Setup -->
<h2>Clone & Setup</h2>
<div class="card">
  <pre><code>git clone {{REPO_URL}}
cd {{PROJECT}}
{{SETUP_COMMANDS}}</code></pre>
</div>

<!-- Environment Variables -->
<h2>Environment Variables</h2>
<div class="card">
  <p>Copy the example env file:</p>
  <pre><code>cp .env.example .env</code></pre>
  <table>
    <thead><tr><th>Variable</th><th>Required</th><th>Description</th></tr></thead>
    <tbody>
      <tr><td><code>{{VAR}}</code></td><td>{{REQ}}</td><td>{{DESC}}</td></tr>
    </tbody>
  </table>
</div>

<!-- Running Locally -->
<h2>Running Locally</h2>
<div class="card">
  <pre><code>{{RUN_COMMANDS}}</code></pre>
  <p class="muted">The app should be available at <code>{{LOCAL_URL}}</code></p>
</div>

<!-- Architecture Overview -->
<h2>Architecture</h2>
<div class="card"><pre><code>{{ASCII_DIAGRAM}}</code></pre></div>
<p>{{ARCHITECTURE_DESCRIPTION}}</p>

<!-- Directory Guide -->
<h2>Where Things Live</h2>
<table>
  <thead><tr><th>Path</th><th>What's in it</th></tr></thead>
  <tbody>
    <tr><td><code>{{DIR}}</code></td><td>{{PURPOSE}}</td></tr>
  </tbody>
</table>

<!-- Common Commands -->
<h2>Common Commands</h2>
<table>
  <thead><tr><th>Command</th><th>What it does</th></tr></thead>
  <tbody>
    <tr><td><code>{{CMD}}</code></td><td>{{DESC}}</td></tr>
  </tbody>
</table>

<!-- Conventions -->
<h2>Conventions</h2>
<div class="card">
  <ul>
    <li><strong>{{CONVENTION}}</strong> — {{EXPLANATION}}</li>
  </ul>
</div>

<!-- First Task Suggestions -->
<h2>Good First Tasks</h2>
<div class="card">
  <ol>
    <li>{{TASK}} — {{WHY_ITS_GOOD_FOR_NEW_DEVS}}</li>
  </ol>
</div>

<!-- Who to Ask -->
<h2>Who to Ask</h2>
<div class="card">
  <table>
    <thead><tr><th>Area</th><th>Person</th></tr></thead>
    <tbody>
      <tr><td>{{AREA}}</td><td>{{PERSON_OR_PLACEHOLDER}}</td></tr>
    </tbody>
  </table>
  <p class="muted">Not sure? Check <code>git blame</code> on the file you're working in.</p>
</div>

4. Publish

uselink publish /tmp/uselink-onboarding-<project>-<timestamp>.html \
  --title "Onboarding Guide -- <project>" \
  --format html

Return the URL to the user.

Gotchas

• NEVER set background or color on body, table, th, td, code, or pre. uselink's viewer injects theme-adaptive CSS that handles light/dark mode automatically. Any hardcoded color in published HTML overrides the viewer's theme and forces a white background in dark mode. Only style layout (padding, margins, borders, border-radius, font-size, grid). Use opacity for muted text instead of color: #888.
• Test the setup commands yourself. Run the commands you're about to document and verify they work. "Clone, install, run" should be copy-pasteable. If a step requires manual intervention (like uselink login), call it out explicitly.
• Don't fabricate team members for "Who to Ask." If you can't determine team members from git blame or README, use placeholder text like "Check git blame" or ask the user.
• Environment variables from .env.example need real descriptions. Don't just list the variable names. Read the codebase to understand what each one does and whether it's required or optional.
• Makefile targets are the best command reference. If a Makefile exists, read it thoroughly — it's usually the canonical list of developer commands.
• HTML-escape all interpolated values. File paths and command output can contain special characters.
• Skip sensitive defaults. If .env.example has API keys or passwords (even dummy ones), note that the user needs to fill them in. Don't publish actual credentials.