gitea/skills/wiki/SKILL.md

name, description

name

description

wiki

Read or write a Gitea wiki page through tools/gitea.sh and tools/hash-id. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks for its ERROR pages, jsc-cli for its CHECK pages, and jsc-meta for its SKILLSET and TOOLING pages. Use for any wiki page in the skill set; not for repo code files.

wiki — read and write Gitea wiki pages

Every wiki operation in the jsc skill set goes through this skill. One entry point, one permission path.

Resolve the wiki location

Different page types can live in different {owner}/{repo} repos, classified by the page-name prefix.

1. Host gate. Confirm GITEA_HOST holds a value in the current shell. When it is missing, ask for it per the jsc-ask:ask rules before any tools/gitea.sh call that reaches the API; otherwise the first thing the user sees is the script's GITEA_HOST is required line instead of a decision-tree question. GITEA_TOKEN needs no inventory here — the script resolves it, retries once with the tea CLI login token, and exits 7 when neither works. Done when GITEA_HOST holds a value.
2. Run tools/gitea.sh wiki-repo {TYPE} (TYPE = the page-name prefix). Allowed types are QUESTION, PLAN, ANALYZE, DELIVER, MAINTAIN, REPO, LOG, LEARN, ERROR, CHECK, REPORT, SKILLSET, and TOOLING. The script reads JSC_WIKI_REPO_{TYPE} first and JSC_WIKI_REPO second, straight from the inherited environment, so take no separate inventory of those two variables. Never borrow another type's repo. Done when the command has printed exactly one {owner}/{repo}, or exited 3 and sent this page type to step 3, or exited 2 on a type outside the list above and stopped the run.
3. On exit 3 (neither variable is set), ask the user for that page type's {owner}/{repo} per the jsc-ask:ask rules, and suggest setting JSC_WIKI_REPO_{TYPE} (can differ per type) or JSC_WIKI_REPO (shared default). Done when the user has supplied one {owner}/{repo} for that page type.

Operations

Action	Command
list pages	tools/gitea.sh wiki-list {owner}/{repo}
read page	tools/gitea.sh wiki-get {owner}/{repo} {page}
write page	write the content to a temp file first, then tools/gitea.sh wiki-put {owner}/{repo} {page} {file} (asks for confirmation first, then creates or updates)
page URL	tools/gitea.sh wiki-url {owner}/{repo} {page} — the page's absolute URL, taken from the API's html_url

When writing a page, link same-type pages with the [[display|page]] form (display text on the LEFT) and cross-type pages with the absolute URL from wiki-url, because [[...]] resolves only inside one wiki. Full rules and the direction trap: references/wiki-links.md.

Exit codes

Route every tools/gitea.sh call in this skill on its exit code. A code with no branch below stops the run and gets reported as it is.

Code	Meaning	What this skill does
0	success	use the output
2	usage error, or a page type outside the allowed list	fix the arguments, then call again; never repeat the same call unchanged
3	wiki-repo: neither JSC_WIKI_REPO_{TYPE} nor JSC_WIKI_REPO is set	go to step 3 and ask
4	HTTP 404: wiki-get and wiki-url found no such page	for a read the caller expects to succeed, stop and report the page name; this is the only code that opens the create path of rule 4 — write the page from the template instead of appending
5	wiki-url: the page exists but the API returned no html_url	stop and report it. Link inside the same wiki with [[display|page]]; a cross-repo link has no absolute URL to point at, so do not fabricate one
7	HTTP 401 or 403 after the tea-token retry: the key is invalid or lacks permission	stop the whole operation and report the key problem. Never read this as an empty or missing page, and never take the create path of rule 4: writing a fresh page over one you could not read destroys the record that is still there
8	any other API failure, HTTP status in the message	stop and report that status; call again only after the cause is fixed

Rules

1. Page names must follow the wiki naming table in the skill guidelines (see jsc-meta/references/guidelines.md).
2. Use tools/hash-id for {HASH} values. It returns the first 8 uppercase SHA-1 hex chars, or H plus the first 7 chars when the raw hash starts with 0-9, A, B, or C. Exit 1 means this machine has neither sha1sum nor shasum: stop, report that one of them has to be installed, and compute no hash by hand — a hand-made page name lands the content on a page nobody else reads.
3. To update a contents page (*_CONTENTS): wiki-get it first, apply the template to append or modify, then wiki-put the whole page back — the write asks for confirmation before it goes out. Never overwrite entries owned by others. Whether the page may be created from the template instead is decided by rule 4, and by nothing else.
4. Only exit 4 means the page is not there yet — this rule binds every "create it if it does not exist" path, without exception. It is not limited to contents pages: a content page (*_{HASH}), a work log, an error page, a report, any page at all, follows the same branch.
   • Correct branch. Read the page with wiki-get. Exit 0 means the page exists, so append or modify the content that came back and wiki-put the whole page. Exit 4 (HTTP 404) is the one and only code that permits creating a new page from the template.
   • Exit 7 and exit 8 abort. Exit 7 (HTTP 401 or 403) and exit 8 (any other API failure) both mean the old content is unknown, never that the page is missing. Stop the operation and report the exit code with its cause. Create no page, write nothing, and do not retry the same call unchanged.
   • Why. Wiki writes in this skill set are append-not-overwrite, and that semantics rests entirely on reading the old page back first. Reading a 401 as a 404 makes the caller believe it holds a brand-new page and wiki-put a fresh template over a live one, and the whole earlier record is gone — the write carries no merge and no backup.
5. Write all wiki content in UTF-8 Traditional Chinese, per the STE100 output rule.
6. Prefer visual forms for page content: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Prose is capped at 3 sentences per section, and a sentence stays only when neither a mermaid diagram nor a markdown table can carry the same information.
7. tools/gitea.sh retries once with the tea CLI login token when GITEA_TOKEN is missing or the response is 401/403. Report a failure only after that retry also fails.