community-publish

---

name: community-publish version: 0.14.1 description: | Publish previews, list on dashboard, open-source projects to community GitHub.

Use when the user wants to share, publish, list, or open-source what they built (e.g. make this dashboard public, share my project, push to GitHub). delivery: script metadata: starchild: emoji: 📦 skillKey: community-publish user-invocable: true disable-model-invocation: false

---

Three independent actions

This skill handles three completely different kinds of sharing. They are NOT stages of one flow and NOT mutually exclusive — a project can be in any combination.

Action	What "share" means here	Audience can	Applies to
publish_preview(preview_id)	Allocate a public URL https://community.iamstarchild.com/{user_id}-{slug}	Open the URL if they know it — point-to-point access	Any running service
list_in_dashboard(slug)	Show the listing on the public Project Dashboard	Discover and browse to it from the gallery	A previously-published preview
open_source(project_dir)	Push project source to the community GitHub repo	Fork the code and run their own copy	Any project (task, service, script)

Critical: do NOT auto-list when publishing. publish_preview() only allocates the URL. Listing is a separate, deliberate user decision. If the user just says "publish my preview" / "公开" without mentioning the dashboard, only call publish_preview(). After it succeeds, you may mention that list_in_dashboard() exists if they want others to discover it.

Service lifecycle (start / stop / health check) lives in the preview tool. This skill only handles the share side.

---

Visibility model — read this before answering anything about who can see a project

A project's "publicness" is two orthogonal switches, not one:

Switch	Off state	On state	Flipped by
URL access	Visiting the URL returns 404 / no service	URL works for anyone who has the link	publish_preview / unpublish_preview
Dashboard discoverability	Listing row has is_public=false (or doesn't exist) — invisible in the public gallery	Listing row has is_public=true — appears in /projects	list_in_dashboard / unlist_from_dashboard

Public URL ≠ public discovery. A preview can be URL-reachable but undiscoverable (the default state right after publish_preview), or listed but URL-down (preview stopped after being listed), or any other combination. Never collapse these into "is it public yet".

Status questions are read-only operations. Whenever the user asks anything like:

• "is it visible / public / discoverable yet?"
• "can other people find it?"
• "上架了吗 / 在 dashboard 上吗 / 别人能看到吗"
• "is the listing live?"

The authoritative answer comes ONLY from a fresh get_listing_status(slug) call. Do NOT infer the answer from "I called publish_preview earlier so it must be visible" — that's exactly the trap (publish_preview leaves is_public=false). Treat your own past actions as suggestive but never authoritative for a state question.

---

Project types — three only

type	What it is	Eligible for publish_preview()?
task	Scheduled cron/interval job	No (no HTTP port)
service	Long-running HTTP service (dashboard, API, page)	Yes — any service can be exposed at a public URL
script	One-shot script	No (no HTTP port)

Note: there is no preview type. If you encounter older docs mentioning it, treat as service.

---

Routing — match user intent to the right surface

User requests fall into two fundamentally different categories. Mixing them up is the #1 source of wrong answers in this skill.

A. Status intents — user wants to know current state

The user is asking a question about how things stand right now. The answer is data, not an action. Always reach for a read endpoint first; never answer from memory of past actions.

Sample phrasing	Action
"is it visible / public / discoverable / live for others?"	get_listing_status(slug)
"上架了吗 / 在 dashboard 上吗 / 别人能不能看到 / 别人能搜到吗"	get_listing_status(slug)
"what URLs do I have published?" / "我发布了哪些"	list_published_previews()
"what's open-sourced?" / "都有哪些开源代码"	list_open_source(...)

B. Action intents — user wants to change state

Sample phrasing	Action	Notes
"publish" / "share" / "make public" / "公开" / "发布" (no qualifier)	publish_preview(preview_id)	Allocates the URL only. Listing is NOT auto-flipped.
"publish the URL" / "share the link" / "let people visit" / "公开访问"	publish_preview(preview_id)	Same.
"list on the dashboard" / "上架" / "show on community" / "make discoverable" / "let people find this" / "发到广场"	list_in_dashboard(slug)	Requires the preview to already exist.
"publish AND list" / "publish and put on dashboard" / "发布并上架"	publish_preview() THEN list_in_dashboard()	Two separate calls in order.
"remove from dashboard" / "下架" / "unlist" / "hide from gallery"	unlist_from_dashboard(slug)	Preview URL stays alive.
"open source" / "open-source the code" / "share the code" / "let others fork" / "开源代码"	open_source(project_dir)	Explicit code-sharing intent.
"unpublish the URL" / "take down the link"	unpublish_preview(slug)	Listing row stays.
"remove the open source" / "delete from GitHub"	remove_open_source(slug)
"fork" / "install someone's project"	fork(source)
Ambiguous after rereading	Ask one question, don't guess	"Do you want it (a) just shareable by URL, (b) also discoverable on the public dashboard, or (c) also have the code open-sourced on GitHub?"

---

Cross-link via publisher: binding

When the same project has BOTH a public URL AND open-sourced code, you want them paired so the frontend renders "View Source" on the listing card and "Visit Live Demo" on the code card. This skill drives that pairing through one explicit binding in project.yaml — no name guessing, no fuzzy matching, no follow-up dialogues.

How to declare the binding

Add a publisher: block to project.yaml:

name: my-app                      # GitHub catalog slug + default for both sides
type: service
version: 1.0.0
publisher:
  code_slug: my-app               # OPTIONAL — defaults to manifest.name
  public_slug: my-app-pub         # OPTIONAL — URL suffix; defaults to code_slug

Both fields are optional. If omitted, both default to manifest.name. Set them only when you want different slugs on each side (e.g. short URL dash for code my-detailed-dashboard).

Either side can be published first

The gateway holds a pending entry until the second side arrives. No ordering requirement, no manual link step.

Order	What happens
open_source first → publish_preview second	open_source records pending entry; publish_preview consumes it and links
publish_preview first → open_source second	publish_preview records pending entry (needs publisher_code_slug arg); open_source consumes it and links
Both at once / rename later	Re-run either side with updated binding; gateway re-links

Calling publish_preview with binding

When publishing the URL FIRST and the code will follow:

publish_preview(
    preview_id="my-app-a3f1",
    slug="my-app-pub",
    publisher_code_slug="my-app",   # so future open_source(my-app) auto-links here
)

If publisher_code_slug is omitted, no pending entry is recorded — the code side will need to declare publisher.public_slug itself in project.yaml to wire the link.

Return value

Both functions return a publisher field showing what binding was sent and a hint describing the cross-link state:

{"ok": True, "url": "...", "publisher": {"code_slug": "my-app"},
 "hint": "Cross-link binding declared. If that code is already open-sourced, it's now linked. If not, the link is pending..."}

You don't need to react to the hint — it's informational. The gateway handles wiring automatically.

Manual repair (rare)

If a pairing was wired wrong (e.g. after a rename or a slug typo), use:

link_to_listing(listing_slug="2004-my-app-pub", code_slug="my-app")

This skips the binding flow and writes the link directly. Don't use this for normal publishing — fix project.yaml's publisher: block instead so the binding survives future republishes.

---

Architecture

                community.iamstarchild.com (single gateway domain)
                              │
            ┌─────────────────┴─────────────────┐
            │                                   │
   ┌────────▼─────────┐                ┌────────▼─────────┐
   │  /api/register   │                │/api/code-projects│
   │  /api/unregister │                │ /publish, /list, │
   │  /api/list       │                │ /unpublish, ...  │
   └────────┬─────────┘                └────────┬─────────┘
            │                                   │
   ┌────────▼─────────┐                ┌────────▼─────────┐
   │ DB: route table  │                │ GitHub:          │
   │ + project_       │                │ Starchild-ai-    │
   │   listings       │                │ agent/community- │
   │ + publisher_     │                │ projects         │
   │   pending_links  │                │                  │
   │                  │                │ Permanent.       │
   │ Service stays up │                │                  │
   │ as long as your  │                │                  │
   │ container runs.  │                │                  │
   └──────────────────┘                └──────────────────┘
     publish_preview()                    open_source()

publisher_pending_links is the cross-link table. Either side writes a pending row, the other side consumes it on arrival.

---

publish_preview() — public URL

publish_preview(preview_id, slug="", title="", publisher_code_slug="")

Map a running service to https://community.iamstarchild.com/{user_id}-{slug}.

• preview_id: from preview(action='serve'). Must be status=running.
• slug: URL suffix only (lowercase alphanumeric + hyphens, 3-50 chars). User_id prefix is added automatically — pass 'my-app', NOT '1463-my-app'.
• title: display name for the listing.
• publisher_code_slug: optional cross-link binding to a code project's slug. Sets up the pending entry so the eventual open_source() call auto-links.

Returns {"ok": True, "url": "...", "publisher": {...}, "hint": "..."}.

Constraints:

• Max 20 published previews per user (gateway returns 429 over).
• Service must be running. Stops working when the container goes down (visitors see offline page).
• Slug stays bound to the port — stop and re-serve, the URL stays valid.
• Only works inside the Starchild Fly container (needs FLY_MACHINE_ID).
• Listing visibility default is is_public=false. A successful publish_preview allocates the URL but creates the listing row in PRIVATE state — strangers cannot discover the project on the dashboard. Discovery requires a separate list_in_dashboard() call. Do NOT tell the user "your project is now public" after only calling publish_preview — say "the URL is live" and offer list_in_dashboard as the next step if they want it discoverable.

Companions:

• unpublish_preview(slug) — remove the public URL. Slug accepts full {user_id}-{suffix} or just suffix.
• list_published_previews() — all currently published preview URLs for this user.

---

list_in_dashboard() — show on Project Dashboard

list_in_dashboard(slug, name=None, description="", cover_url=None, tags=None)

Make a published preview discoverable in the public Project Dashboard at https://community.iamstarchild.com/projects. Without this, the preview URL works but is invisible to anyone who doesn't already know it.

• slug: the full slug returned by publish_preview() (i.e. {user_id}-{suffix}). The gateway's ownership check uses this exact value.
• name: dashboard card display name. Defaults to slug.
• description: ≤500 chars.
• cover_url: must be on storage.googleapis.com, image.thum.io, or api.microlink.io. Other domains rejected with 400. If omitted, the gateway captures a screenshot asynchronously.
• tags: ≤5 tags, ≤20 chars each.

Returns {"ok": True, "listing": {...}, "url": "...", "dashboard_url": "..."}.

Constraints:

• Requires publish_preview() to have run first for the same slug — returns 404 with a clear error otherwise.
• Idempotent: calling again with different name/tags updates the existing listing.
• Listings created via publish_preview() start as private (not on dashboard) — list_in_dashboard() is the ONLY way to make them discoverable.

Companions:

• unlist_from_dashboard(slug) — remove from dashboard, keep URL alive.
• get_listing_status(slug) — read-only check: returns {ok, exists, is_public, listing}. Note: only public listings are observable through this — if the gateway returns 404, the listing is either nonexistent OR private (no way to distinguish).

---

open_source() — push code to GitHub

open_source(project_dir, version_bump="patch", message="", make_discoverable=True)

Push project source to community-projects/projects/{user_id}/{slug}/ on GitHub. Versioning is delegated entirely to git history — there's no {version}/ snapshot directory and no per-type bucket above the slug. The type field inside project.yaml stays around as runtime metadata (so forks know whether to schedule, run-once, or expose a service) but no longer affects the storage path.

• project_dir: e.g. output/projects/my-task
• version_bump: patch | minor | major | none
• message: commit message body describing what this version changed. You (the agent) should always compose this based on the actual code changes you made in this session — never leave it blank if you know what changed, never ask the user to write it. Aim for one to three short lines. Don't list every file; describe the user-visible change. If the user explicitly said "just publish", use a one-line summary like "Initial publish" or "Re-publish without changes".
• make_discoverable (default True): "open source" matches the user-intuition default of "make this fully public". After pushing the code, if a paired preview/listing row exists for the same slug (via publisher.public_slug / publisher.code_slug / manifest.name), it is automatically flipped to public on the Project Dashboard. Pure libraries / pure scripts with no preview row are skipped silently — no side effect. Pass make_discoverable=False when the listing should stay private.
• Returns {"ok": True, "github_url": ..., "version": ..., "publisher": {...}, "auto_list": {...}, "hint": "..."}
  • auto_list.attempted: whether the auto-list path was tried (False when make_discoverable=False)
  • auto_list.listed: True on success, False otherwise
  • auto_list.reason: "no_preview_for_slug" (pure code case — expected) or "list_failed" with error field

Commit message style — write like a normal git commit body:

✅ "Add WebSocket reconnect on dropped connections; refactor prompt builder for shared state." ✅ "Fix funding-rate sign convention; add unit test for negative-funding path." ❌ "Updated 3 files" (uninformative) ❌ "Modified src/index.html, src/main.py, project.yaml" (lists files instead of intent) ❌ "User asked to publish" (describes the request, not the change)

Companions:

• fork(source, dest_dir=None) — install someone else's open-sourced project locally
  • source: "user_id/slug" (always pulls current state — older snapshots live in GitHub commit history)
  • For task type: registers as paused, returns next_step instructions
  • For service type: returns ready-to-serve info
• list_open_source(type=None, tag=None, user=None, q=None) — browse the GitHub catalog
• get_open_source(source) — fetch one project's full metadata
• remove_open_source(slug) — delete project directory from GitHub catalog (owner only). Git history of the deletion + previous commits is preserved in the repo's commit log.
• validate_open_source(project_dir) — pre-flight check before publishing

Project structure

Every project under output/projects/{slug}/:

project.yaml      # metadata (name, version, type, env_required, sc_proxy, publisher)
PROJECT.md        # required sections: What / Required env / How to start / Outputs / Troubleshooting
.env.example      # all env vars with placeholder values
.gitignore        # secrets blacklist
src/
  ├── run.py       # for type=task (must start: # -*- task-system: v3 -*-)
  ├── index.html   # for type=service (or app.py + frontend)
  └── main.py      # for type=script

Don't conflate the two list functions

list_published_previews() returns live URLs (preview side). list_open_source() returns open-sourced code (GitHub side). Different datasets — never quote one number to answer a question about the other.

---

Usage from a bash block

python3 - <<'EOF'
import sys
sys.path.insert(0, "/data/workspace/skills/community-publish")
from exports import (
    # Public URL
    publish_preview, unpublish_preview, list_published_previews,
    # Open source code
    open_source, remove_open_source, fork,
    list_open_source, get_open_source, validate_open_source,
    # Manual repair (rare)
    link_to_listing,
)

# Cross-linked publish: declare publisher in project.yaml first, then both
# sides auto-pair regardless of order.
print(publish_preview(preview_id="my-app-a3f1", slug="my-app",
                      publisher_code_slug="my-app"))
print(open_source("output/projects/my-app", version_bump="patch"))
EOF

---

Behavioral rules

• Show the diff before open_source(). After validate_open_source, summarize what's about to be pushed (file list, version, type, tags, env_required) and ask for confirmation. Exception: explicit "publish without confirmation" or re-publish of a known good project.
• Never auto-run setup.sh on fork. Show the command, let the user confirm.
• Always collect env in one batch on fork. Read project's env_required, diff against workspace/.env, call request_env_input ONCE with the missing keys. Don't ask one-by-one.
• Slug rules: lowercase alphanumeric + hyphens, 3-50 chars, no leading/trailing hyphen. Skill auto-strips duplicate {user_id}- prefix if you accidentally include it.
• Version rules (open_source): strict semver. Re-publishing same version is rejected. New version must be > current latest.
• Type immutability (open_source): once published as task, can't change to service later. Pick a different slug.
• URL ≠ code: a public URL going down (container off) does NOT remove the open-source code, and vice versa. They're independent.
• Don't manually call link_to_listing() in the normal flow. The publisher: binding handles cross-linking. Manual link is only for repair.

---

Common gotchas

Symptom	Cause	Fix
publish_preview: Preview not found	Wrong preview_id, or service was stopped	Check /data/previews.json, restart with preview(action='serve')
publish_preview: 429 Too many published previews	Hit 20-per-user gateway cap	unpublish_preview() something old first
publish_preview: FLY_MACHINE_ID not set	Running locally, not in Starchild container	URL publish only works in the production container
open_source: 400 Validation failed: env names not in .env.example	Listed MY_KEY in env_required but forgot .env.example	Add the missing key to .env.example
open_source: 400 Possible secret detected	Secret scanner found a real-looking API key	Move to env var; .env.example value should be your-key-here

| open_source: 400 Type cannot change after publish | Trying to switch task ↔ service ↔ script | Pick a different slug | | remove_open_source: 403 Permission denied | Trying to remove someone else's project | Only the owner can remove | | Cross-link not appearing on frontend | Binding mismatch between sides | Check both sides' slugs match the publisher: block; or use link_to_listing to repair | | Forked task doesn't run | Auto-registered as paused | Tell user: scheduled_task(action='activate', job_id={id}) |

---

References

• lib/manifest.py — project.yaml parser/writer + semver helpers
• lib/validate.py — local pre-publish validation (mirrors gateway-side checks)
• lib/install.py — type-specific install handlers (task/service/script)
• lib/gateway.py — HTTP client for /api/register (URL side) and /api/code-projects/* (code side)