Publishing

Quick publish in the app

The default path is the create-project form. It stays minimal first, with advanced metadata hidden until it matters.

A user should be able to publish a project in minutes without deciding everything up front. Stable docs, screenshots, install details, and access states can be refined after the first publish.

• Title, tagline, description, demo URL, and visibility are the default fields.
• Repo, docs, install, download, cover image, tags, and stack live in advanced details.
• Source access and distribution access are explicit so private work is not accidentally exposed.

UI quick start

Use the in-app form when you want the lightest publish flow. This is the default path for most users and it should stay minimal.

Requirements:

• A signed-in vicode account
• A project title, short summary, and description
• An optional demo URL if the work is already live

Steps:

1. Open /projects/new.
2. Fill title, tagline, description, and visibility first.
3. Publish the project, then refine the page with notes, voice memos, comments, covers, or written docs.

Use sourceAccess of private or none if the project should be visible without exposing the repository.

GitHub import

Use GitHub import when the repo is public and you want to prefill the create form quickly.

Requirements:

• A public GitHub repository
• A repository title, README, topics, or homepage worth importing

Steps:

1. Paste the repository URL.
2. Review the access state instead of assuming a public install or download path.
3. Publish, then add richer written docs later if needed.

CLI

Use the local CLI if you are publishing from a local folder or running a repeatable agent workflow.

Requirements:

• A publishing token from /profile/edit
• A local project directory
• The vicode API base URL

set VICODE_API_URL=https://your-vicode-host
set VICODE_TOKEN=vct_your_token_here
npm run vicode -- publish --dir D:\Projects\MyProject
npm run vicode -- update --project my-project --dir D:\Projects\MyProject --sync-docs

API

Use the API when an agent or backend service needs to create or update projects without the browser.

Requirements:

• A publishing token with the right scope
• Bearer auth on every request
• Secure https URLs for external links in production

POST /api/projects
PATCH /api/projects/:id

Agents should publish through the API instead of writing directly to the database.

Written docs versus README fallback

Project owners can write richer docs directly in project settings. Those written docs become the primary source for the project docs page.

README parsing remains the fallback when written docs are missing. That keeps publishing fast, while still giving owners a stable way to explain setup, architecture, limitations, and current direction.

GitHub import

For public repos, GitHub import can prefill title, tagline, repo URL, demo URL, and tags. It is optional and should stay fast.

Agent and power-user publishing

Agents and scripts should publish through vicode, not by writing directly to the database. The secure path is a scoped API token plus the project ingestion API.

• Tokens are created by a signed-in user.
• Tokens are shown once and stored hashed.
• Scopes stay narrow.
• Publishing through the API uses the same validation and access model as the app form.