website

quirq home base

Everything quirq builds. One little space.

A desktop for the apps, experiments, tools, and open source projects in the quirq GitHub organization. Explore a repository, read its docs, follow a project's progress, or open an app in its own window.

Run locally · Map an app · Development guide · Repository audit

A home for your apps

The desktop uses Gatsby 4, React 18, and Tailwind CSS, with a shared flex-based window system and layouts that respond to each window's width. The interface adapts desktop components and artwork from PostHog/posthog.com; its old marketing pages and service integrations have been removed.

Opening a repository shows public metadata and documentation. It does not install or run its code. App websites open in launch windows when their framing policy permits it; Open in new tab remains available when a website cannot be shown here.

Run locally

Use Node.js 24.x and pnpm 10.23.0, as pinned in .nvmrc and package.json.

git clone https://github.com/quirq-ai/website.git
cd website
corepack enable
corepack prepare pnpm@10.23.0 --activate
pnpm install --frozen-lockfile
pnpm start

Open localhost:8001. The development server binds to 127.0.0.1; stop it with Ctrl+C.

The committed snapshots are enough to start and build the site. No GitHub token, CMS account, or environment file is required.

From GitHub to the desktop

flowchart LR
    GitHub[Public GitHub repositories] --> Sync[pnpm apps:sync]
    Sync --> Snapshot[Committed snapshot]
    Mapping[quirq.apps.json] --> Catalog[Shared catalog]
    Snapshot --> Catalog
    Catalog --> Routes[Gatsby app routes]
    Catalog --> Desktop[Home · dock · search · windows]
    GitHub --> Live[Anonymous browser reads]
    Live --> Desktop

Built pages use src/data/quirq-repositories.json, mapped by quirq.apps.json. Builds validate this saved data and do not fetch GitHub.

The browser refreshes the public repository list every five minutes while the tab is visible. Repository docs and the organization's desktop profile come from public GitHub files. New repositories can open through /apps/* before the next deployment. If GitHub is unavailable, the catalog keeps its last usable list.

Public, non-archived repositories and forks are included by default. This organization's mapping includes .github too. Visibility is an explicit catalog choice; private repository metadata never belongs in the snapshots.

Give an app its own identity

Edit a repository entry in quirq.apps.json:

{
    "xo-space": {
        "name": "XO Space",
        "path": "/xo-space",
        "icon": "planet",
        "color": "purple",
        "featured": true,
        "window": { "width": 1080, "height": 760 }
    }
}

Choose an icon, color, description, route, visibility, launch destination, or a custom template under src/templates/. Repository types come from the organization's role property on GitHub. Type filters, badges, and ordering appear once three types are in use; search always matches types. Keep app choices in the mapping so Home, desktop icons, search, and routes agree.

The app mapping guide covers every setting, live updates, documentation links, and launch-window framing rules. A destination's security headers decide whether it can be embedded; exact trusted quirq.dev origins can be configured through frameOrigins.

To refresh the built catalog:

pnpm apps:sync
pnpm apps:check

Review and commit the generated snapshot. Restart Gatsby after changing routes, then rebuild and deploy to refresh server-rendered pages. After hiding a repository, run pnpm apps:sync or the offline pnpm apps:prune to remove its README from the bundled snapshot.

Follow projects from idea to use

/projects groups repositories using quirq.projects.json. Phases come from repository evidence:

pnpm projects:sync refreshes the committed phase snapshot using public repository trees, star counts, and aggregate contributor counts. It stores no contributor names or emails. A manual phase override needs a phaseReason. Every public repository must belong to a group or be explicitly hidden.

The /v0 app explains quirq infra and shows its public live state. See the development guide for workflow ownership.

Work on the site

pnpm apps:check
pnpm projects:check
pnpm source:check
pnpm test
pnpm build

Preview the production output with pnpm serve -H 127.0.0.1 -p 9000. Before handing off UI changes, check wide and narrow windows in both themes, search, direct app routes, and the window lifecycle. Format only changed files.

Read AGENTS.md and the relevant component README before editing shared code. The development guide covers commands, environment variables, deployment, and troubleshooting. The repository audit records the cleanup, intentionally retained upstream material, and verification limits.

Optional analytics and error tracking use quirq's own PostHog project. Set the public GATSBY_POSTHOG_KEY at build time to enable pageviews, clicks, and uncaught error reporting through the /ingest rewrites. Without a key, the browser loads no analytics script. See environment variables and .example.env.

Attribution and licensing

quirq's original additions retain the Apache 2.0 license. Inherited desktop code and artwork retain the separate upstream terms, including their website reuse restriction. Third-party vendored code keeps its own notices. The quirq name, marks, and approved brand art are reserved.

Read LICENSING.md before reusing or redistributing this repository. Adding quirq branding does not relicense inherited material.