README sections

SilentForge

Transform public GitHub repositories into portable, evidence-backed static presentation sites. SilentForge reads README content, metadata, file trees, releases, and lightweight code signals, then emits self-contained HTML you can preview, zip, and deploy anywhere. Install from npm (npm install -g silentforge) or run instantly with npx silentforge. Use the reposite / silentforge CLI for one-shot generation, or the lo…

# Generate a static presentation site (npx — no install)
npx silentforge init vercel/next.js

# Open the generated index.html (macOS example)
open vercel/next.js-site/index.html

# Launch the local Workbench UI
npx silentforge web

Screenshots

---

Table of contents

Overview Quick start Usage Examples How it works Features Requirements Installation and distribution Deploy to GitHub Pages GitHub authentication Workbench CLI reference Generated output Presentation modes and themes Internationalization Environment variables Design guarantees FAQ Development License ---

Overview

SilentForge targets teams and maintainers who need a credible, offline-capable project narrative without standing up a docs platform or hand-authoring a landing page from scratch. Both entry points share the same generation engine, so Preview, ZIP download, and CLI output are structurally identical. A typical generated site includes a hero, features, visuals, usage commands, README deep-dives, tech stack, architectu…

Quick start

Requires Node.js 20+. Pick one install path: Optional local preview after generation: ---

# Generate a static presentation site (npx — no install)
npx silentforge init vercel/next.js

# Open the generated index.html (macOS example)
open vercel/next.js-site/index.html

# Launch the local Workbench UI
npx silentforge web

Usage

Typical workflows after Quick start: Publish to GitHub Pages: generate in Workbench, open Deploy, copy the workflow YAML into .github/workflows/silentforge-pages.yml, enable Settings → Pages → GitHub Actions, then push to main. See Deploy to GitHub Pages. ---

# CLI — generate to a folder and open locally
npx silentforge init owner/repo
open owner/repo-site/index.html    # macOS; adjust path on Linux/Windows

# Workbench — interactive preview, diagnostics, ZIP, deploy guide
npx silentforge web
# → http://127.0.0.1:4177/

# Custom output directory and locale
npx silentforge init owner/repo -o my-site --locale zh

# Optional AI-assisted chapter ordering (Codex login preferred; OPENAI_API_KEY as fallback)
codex login   # once, if using local Codex
npx silentforge init owner/repo --ai
OPENAI_API_KEY=sk-… npx silentforge init owner/repo --ai

Examples

Try SilentForge on well-documented public repositories: See examples/README.md for more detail. Live demo: SilentForge on GitHub Pages — live and auto-updated from this repository on every push to main (workflow). Open it to preview scroll-story chapters, extracted commands, and architecture signals before deploying your own repo. ---

How it works

1. Ingest — Resolve owner/repo, fetch repository metadata, README, releases, and file tree via the GitHub API. 2. Extract — Parse README structure (features, install, usage, FAQ, screenshots, sections) and derive a lightweight code wiki (stack, entry files, configs, module map, Mermaid diagram). 3. Diagnose — Score repository readiness and surface gaps before publication. 4. Plan — Select presentation mode, theme, a…

Features

Scroll-story presentation sites — sticky chapter navigation, detail routes, three themes (Dark Signal, Editorial Light, Blueprint), five narrative modes or auto-selection from repository signals Code wiki — detected stack, entry files, config signals, directory summaries, module map, and offline Mermaid architecture diagram Repository diagnostics — readiness score with strengths, gaps, and recommendations in Workben…

Requirements

---

Installation and distribution

npm (recommended) Published on npm as silentforge. Requires Node.js 20+. npm install -g fails with EACCES? On macOS/Linux, npm may lack permission to write symlinks under /usr/local/bin. Use npx silentforge instead, or see Global install permission errors below. The reposite and silentforge commands both point to the same CLI entrypoint declared in package.json: Build from source Run without installing the global co…

# One-shot generation (no install)
npx silentforge init owner/repo

# Workbench UI
npx silentforge web

# Global install — adds reposite + silentforge to your PATH
npm install -g silentforge
reposite init owner/repo
reposite web

# Project-local install (optional)
npm install silentforge
npx silentforge init owner/repo

npm (recommended)

Published on npm as silentforge. Requires Node.js 20+. npm install -g fails with EACCES? On macOS/Linux, npm may lack permission to write symlinks under /usr/local/bin. Use npx silentforge instead, or see Global install permission errors below. The reposite and silentforge commands both point to the same CLI entrypoint declared in package.json:

# One-shot generation (no install)
npx silentforge init owner/repo

# Workbench UI
npx silentforge web

# Global install — adds reposite + silentforge to your PATH
npm install -g silentforge
reposite init owner/repo
reposite web

# Project-local install (optional)
npm install silentforge
npx silentforge init owner/repo

Build from source

Run without installing the global command: Install reposite onto your PATH: Alternatively, after npm run build:

git clone https://github.com/ingeniousfrog/SilentForge.git
cd SilentForge
npm install
npm run build

Desktop packaging (DMG / EXE)

Native installers are planned. Until then, distribution is build-from-source or npm link / global install as above. A packaged app will bundle the compiled dist/ output and launch reposite web locally—no separate Node install required on the user's machine.

Verify the install

Open /index.html after reposite init, or serve the folder with any static file server. ---

reposite --help
reposite web
# open http://127.0.0.1:4177/

Deploy to GitHub Pages

SilentForge publishes a static presentation site generated from the target repository itself—README, metadata, file tree, and code signals—not a hand-written marketing page. The Live demo is this product applied to this repository. One-time prerequisite (every repository) GitHub requires a manual Pages enablement before the first Actions deploy can succeed: 1. Open your repository Settings → Pages → Build and deploy…

[![Presentation site](https://img.shields.io/badge/Presentation-SilentForge-6366f1?style=for-the-badge)](https://YOUR_USER.github.io/YOUR_REPO/)

One-time prerequisite (every repository)

GitHub requires a manual Pages enablement before the first Actions deploy can succeed: 1. Open your repository Settings → Pages → Build and deployment. 2. Set Source to GitHub Actions (not "Deploy from a branch"). 3. Save. Skipping step 2 causes the workflow to fail at configure-pages with Get Pages site failed, or the deploy job to return status 404. After enabling Pages, open Actions, select Deploy SilentForge pre…

SilentForge demo site (this repo)

Live now: https://ingeniousfrog.github.io/SilentForge/ .github/workflows/silentforge-pages.yml is already committed. On every push to main it: 1. Checks out the repo and runs npm ci && npm run build. 2. Generates a presentation site for ${{ github.repository }} into site/. 3. Publishes site/ to GitHub Pages. First-time setup (only if you fork or clone into a fresh repo without Pages enabled): 1. Enable Pages: Settin…

Any other repository

1. Complete the one-time prerequisite above. 2. Copy .github/workflows/silentforge-pages.yml into your repo—or generate locally in Workbench, open Deploy, and copy the workflow YAML. 3. Push to main or run the workflow manually from Actions. Other repos use the Workbench Deploy workflow template with npx --yes silentforge@latest init ${{ github.repository }} -o site --locale en (requires silentforge >= 0.1.1 on npm)…

[![Presentation site](https://img.shields.io/badge/Presentation-SilentForge-6366f1?style=for-the-badge)](https://YOUR_USER.github.io/YOUR_REPO/)

GitHub authentication (optional)

SilentForge reads public repository data through the GitHub REST API (metadata, README, releases, file tree). Authentication is optional but recommended: unauthenticated requests share a low hourly limit (~60/hour/IP); an authenticated token raises the limit substantially (~5,000/hour). The token is used only when calling api.github.com. It is never sent to OpenAI or any other third party. Workbench behavior: Token…

Workbench

Start the local Workbench from source: Open http://127.0.0.1:4177/ Custom host or port: Run against the compiled CLI entrypoint: Workflow 1. Appearance — Toggle Dark / Light in the header (defaults to system preference; persisted as silentforge.uiTheme after manual selection). 2. Locale — Switch EN / 中文 (persisted as silentforge.locale; affects Workbench copy and the next generation job). 3. GitHub token (optional)…

npm run web

Workflow

1. Appearance — Toggle Dark / Light in the header (defaults to system preference; persisted as silentforge.uiTheme after manual selection). 2. Locale — Switch EN / 中文 (persisted as silentforge.locale; affects Workbench copy and the next generation job). 3. GitHub token (optional) — Expand GitHub access (optional) if you hit rate limits or generate frequently. Token stays on your machine; see GitHub authentication. 4…

Output settings

Workbench Settings → Output settings control the generated site only—not the Workbench shell: Optional AI-assisted structure arranges extracted repository data with local Codex when logged in, otherwise with OpenAI when OPENAIAPIKEY is set. Facts remain source-bound; the pipeline falls back to local rules on failure or validation errors. ---

CLI reference

reposite init Generate a static presentation site from a repository. Examples: reposite web Run the local Workbench server. ---

reposite init https://github.com/openai/openai-node
reposite init openai/openai-node

`reposite init <github-repo-url>`

Generate a static presentation site from a repository. Examples:

reposite init https://github.com/openai/openai-node
reposite init openai/openai-node

`reposite web`

Run the local Workbench server. ---

reposite web
reposite web --host 127.0.0.1 --port 4177

Generated output

reposite init writes a self-contained directory: Content sources (never fabricated): README: title, summary, features, install/usage, FAQ, screenshots, links, long-form sections GitHub metadata: stars, topics, license, releases, default branch, language, homepage Code wiki: project structure, stack detection, entry files, config files, module map, Mermaid diagram Readiness diagnostics (also visible in Workbench Over…

Presentation modes and themes

Modes Generated-site themes Set via Workbench Output settings or --theme on the CLI. auto follows the selected presentation mode. Chapter kinds features, visuals, usage, readme-insights, technology, architecture, resources The hero chapter is always included. Enabled chapters without matching repository content are omitted. ---

Modes

Generated-site themes

Set via Workbench Output settings or --theme on the CLI. auto follows the selected presentation mode.

Chapter kinds

features, visuals, usage, readme-insights, technology, architecture, resources The hero chapter is always included. Enabled chapters without matching repository content are omitted. ---

Internationalization

Switching Workbench locale does not retroactively translate past job events; it affects the UI and the next generation run. ---

Environment variables

Copy .env.example for a commented starter template. On Windows, local Codex via PTY requires node-pty; macOS/Linux can fall back to the script command when PTY is unavailable. Workbench-local preferences (browser localStorage, not environment variables): silentforge.locale, silentforge.uiTheme, silentforge.githubToken (when "Remember on this device" is enabled). ---

Design guarantees

---

FAQ

Do I need a GitHub token? No for occasional public repos. A personal access token helps when you hit API rate limits (~60 requests/hour unauthenticated vs ~5,000/hour authenticated). Global install permission errors (EACCES) If npm install -g silentforge fails with EACCES: permission denied, symlink ... -> /usr/local/bin/reposite, npm cannot write global bin links to a system directory. This is common on macOS—not a…

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# add to ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.npm-global/bin:$PATH"

Do I need a GitHub token?

No for occasional public repos. A personal access token helps when you hit API rate limits (~60 requests/hour unauthenticated vs ~5,000/hour authenticated).

Global install permission errors (`EACCES`)

If npm install -g silentforge fails with EACCES: permission denied, symlink ... -> /usr/local/bin/reposite, npm cannot write global bin links to a system directory. This is common on macOS—not a SilentForge bug. Easiest: skip global install and use npx silentforge init … or npx silentforge web (Quick start). Recommended for daily use: point npm’s global prefix to a directory you own: Then run npm install -g silentfo…

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
# add to ~/.zshrc or ~/.bashrc:
export PATH="$HOME/.npm-global/bin:$PATH"

Is the Live demo the official SilentForge website?

No—it is a generated presentation site built from this repository by SilentForge itself. Use it to preview output quality and chapter layout, not as a separate marketing site. Forks or fresh clones still need the one-time Pages setup.

Can I deploy to hosts other than GitHub Pages?

Yes. Download the ZIP or upload the output folder to Vercel, Cloudflare Pages, Netlify, or any static host. Workbench Deploy includes copy-paste commands.

Does SilentForge work on private repositories?

The current release targets public repositories. Private repo support is planned.

Will SilentForge invent features not in my README?

No. Sections without repository evidence are omitted. Optional AI may reorder chapters but must cite extracted signals; failures fall back to local rules. ---

Development

Project layout (selected): ---

npm test                 # unit tests
npm run test:coverage    # coverage report
npm run dev -- init owner/repo   # CLI via tsx
npm run web              # Workbench via tsx

License

Apache-2.0 — see LICENSE.