AGENTS.md and CONTRIBUTING.md both require docs updates when auth flows or
deployment config change; this batch changed both and touched no docs.
03-authentication-design.md described adding a provider as "branch on
registrationId inside CustomOAuth2UserService", which the
ProviderOAuth2UserService strategy supersedes. Rewrites that recipe:
register an OAuthClaimsExtractor bean per provider, add a
ProviderOAuth2UserService only when the userinfo response is non-standard,
and note that the login page needs no code change. Also records the
provider-side obligations that are easy to get wrong -- stable subject with
no fallback, emailVerified only on proven ownership, bounded remote calls,
no subject in logs -- and un-comments the config example, which still
listed GitLab as a future possibility.
faq.md told operators to delete "the github and gitlab blocks" to hide SSO
buttons. That advice was already incomplete and gets worse per provider, so
it now explains the config-driven mechanism: an empty client id keeps the
entry off the login page, no file edit needed.
09-deployment.md listed only the GitHub credentials. Adds GitLab and Feishu,
and flags a deployment trap: Feishu emails are admin-imported so
emailVerified is always false, and skillhub.access-policy.mode=EMAIL_DOMAIN
denies every unverified email, which would reject all Feishu logins.
Squares the Feishu logo viewBox. It was 407.87x324.19 while login-button
renders it in a square w-5 h-5 box, so the mark was distorted.
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Resolve open npm Dependabot alerts for the web app and docs site by refreshing dependency overrides and lockfiles.
Also sets the staging web forwarded-proto default so `make staging` can render the shared Nginx template when using the bare nginx image.
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
* fix(api): tell callers why a request was forbidden
The scope filter already computes an exact reason ("Missing API token
scope: skill:delete", "API token cannot access endpoint: /x") and the
access-denied handler discarded it, returning a bare "Forbidden" for
every case: missing scope, endpoint closed to API tokens, and paths
that simply don't exist. Clients cannot tell those apart, so they
guess — the published CLI reports every 403 as "token may lack
required scope", which sent us debugging token scopes for an hour when
the real causes were a revoked token and a mistyped namespace path.
The reason now rides in the response via a new error.forbidden.detail
message (en + zh), and is logged alongside the exception type.
Signed-off-by: Gal Eyal <gal.e@popai.health>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
* fix(api): safely expose API token denial reasons
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---------
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
* docs(faq): add community-sourced deployment and operations Q&A
Adds entries collected from real user-support threads to the reference FAQ
(both zh and en):
- 502 on auth APIs while the page loads, traced to server startup failure
on the SKILLHUB_DOWNLOAD_ANON_COOKIE_SECRET placeholder guard
- config changes not taking effect (.env.release.example vs .env.release,
restart vs recreate)
- built-in skill sync failure in offline environments
- upgrade path with Flyway auto-migration and volume retention
- external dependencies and the lack of MySQL support
- granting SUPER_ADMIN to an OAuth account via the bootstrap admin
- telling CLI and server versions apart
- installing skills into a target directory on an intranet
Signed-off-by: FenjuFu <fufenjupku@gmail.com>
* docs(faq): move entries to the published docs source and fix inaccuracies
Move the new FAQ entries from document/ (a generated tree that the docs
build does not read) to docs/skillhub/, which is what make docs-build and
the Pages deploy actually publish.
Also address review feedback:
- drop the SKILLHUB_BUILTIN_SKILLS_ENABLED tip; compose.release.yml does
not pass that variable through, so setting it has no effect
- correct the dependency list: object storage defaults to local, S3 is
recommended for production
- soften the 502 wording, since upstream/DNS/network can also cause it
- state the 32-character minimum for the cookie secret
- give a real bulk-install example and qualify v0.2.12 as a server version
- drop entries already covered by existing upgrade/MySQL/version questions
Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
* docs(faq): correct deployment and admin guidance
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
* docs(faq): fix remaining recreate guidance
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
* docs(faq): clarify bulk install paths
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
---------
Signed-off-by: FenjuFu <fufenjupku@gmail.com>
Signed-off-by: FenjuFu <92919259+FenjuFu@users.noreply.github.com>
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Co-authored-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
Also add Python CodeQL coverage in the security workflow so repository-level script regression checks stay green when Python source exists.
Signed-off-by: dongmucat <1127093059@qq.com>
Add more community-sourced questions (both Chinese and English):
- Troubleshooting CLI `skillhub publish` returning 400 (name conflict,
SKILL.md location/frontmatter, namespace membership, etc.)
- Required skill package structure (SKILL.md in root)
- "malformed input" on publish caused by non-UTF-8 / Chinese-path zips
- Per-package file-count limit and how to raise it
- Minimum server version for CLI features (v0.2.7+)
- PostgreSQL-only (no MySQL); plugins not distributable yet
- How to check server/CLI versions and customize via secondary dev
Signed-off-by: FenjuFu <fufenjupku@gmail.com>
Add questions frequently raised in the user community that were not yet
covered in the SkillHub FAQ, for both Chinese and English pages:
- Recommended deployment via the one-line script vs manual image pulls
- Redirected back to login page after deploying (manual deployment)
- Changing the admin password / why env changes need a restart
- Password change/reset requires email code (SMTP setup)
- Skill naming (English only; Chinese names error in OpenClaw)
- Whether unreviewed skills can be downloaded
- Hiding/removing GitHub & GitLab SSO login options
- Built-in Skill Scanner: iFLYTEK integration over Cisco's scanner (Apache-2.0)
- Which cisco-ai-skill-scanner version is used (unpinned in Dockerfile)
- Note that upgrades preserve registered skills; online docs link
Signed-off-by: FenjuFu <fufenjupku@gmail.com>
- Distinguish user vs project install scope via explicit --scope flag
- Interactive mode prompts for scope when --scope/--agent/--dir not provided
- Non-interactive bare install preserves existing behavior (backward compatible)
- Mutual exclusion: --dir cannot be combined with --scope or --agent
- Symmetric fallback: --scope user falls back to ~/.agents/skills,
--scope project falls back to <cwd>/.agents/skills
- Strict TTY check requires both stdin and stdout TTY plus no --json
- Scope-aware candidate generation avoids root.startsWith(cwd) misjudgement
when cwd === home or paths overlap
- Correct gemini-cli (.gemini/skills) and kiro-cli (.kiro/skills) paths
in install path tables across README and guide docs
- Note CLI fallback uses .agents/skills (with s) in skill protocol doc
- Add publish script with env validation, git checks, and build/test/pack preflights
- Add comprehensive test suite for publish workflow (302 lines)
- Update cli/package.json with @astron-team scope and full npm metadata
- Add README.md with user-focused documentation and registry info
- Add .env.example template for publish configuration
- Add Apache 2.0 LICENSE
- Add Makefile targets for build/test/lint/typecheck/publish workflows
- All publish targets include .env.local validation
- Update installation instructions across all documentation to use @astron-team/skillhub
Document the full CLI workflow so users can understand configuration precedence, install targets, local state files, troubleshooting, and local verification steps.
- Add Aliyun mirror config in server/.mvn/settings.xml
- Update maven-wrapper.properties to use Aliyun mirror for Maven distribution
- Add detailed error messages in Makefile when backend startup fails
- Add troubleshooting section in quickstart.md for China developers
- Add FAQ entry for local development startup issues
- Update README with link to local development guide
* docs: simplify runtime script usage
Unify to use runtime.sh for all deployment commands, removing the
distinction between "official images" and "Aliyun mirror". The --aliyun
parameter is preserved for users in China to specify the mirror.
Changes:
- Remove runtime-github.sh references, use runtime.sh uniformly
- Default command uses GHCR images
- Add --aliyun parameter for China users
- Update README.md, README_zh.md, and docs/skillhub/ quickstart files
* docs: consolidate documentation links with clear descriptions
Merge the two documentation links into a single "Documentation" section
with clear descriptions of each:
- User Guide: skill publishing, search, CLI usage
- Developer Docs: architecture, API reference, deployment
This makes it easier for users to find the right documentation.
* docs: consolidate documentation links with clear descriptions
Merge the two documentation links into a single "Documentation" section
with clear descriptions of each:
- User Guide: skill publishing, search, CLI usage
- Developer Docs: architecture, API reference, deployment
This makes it easier for users to find the right documentation.
* fix: include --home parameter in shutdown command
When starting with a custom --home directory, the generated shutdown
command now includes the same --home parameter to ensure it can find
the correct compose files.
* docs: add Kubernetes deployment guide with overlays structure
- Restructure k8s configs with base/overlays pattern for flexibility
- Add overlays/with-infra for full deployment (PostgreSQL + Redis)
- Add overlays/external for external database scenarios
- Add comprehensive ConfigMap with bootstrap admin settings
- Fix health check path to /actuator/health (auth issue)
- Add SKILLHUB_API_UPSTREAM env for frontend
- Set SESSION_COOKIE_SECURE=false for HTTP environments
- Add Chinese and English documentation in docs/skillhub/
* docs: update k8s README with complete config reference
* docs: simplify runtime script usage
Unify to use runtime.sh for all deployment commands, removing the
distinction between "official images" and "Aliyun mirror". The --aliyun
parameter is preserved for users in China to specify the mirror.
Changes:
- Remove runtime-github.sh references, use runtime.sh uniformly
- Default command uses GHCR images
- Add --aliyun parameter for China users
- Update README.md, README_zh.md, and docs/skillhub/ quickstart files
* docs: consolidate documentation links with clear descriptions
Merge the two documentation links into a single "Documentation" section
with clear descriptions of each:
- User Guide: skill publishing, search, CLI usage
- Developer Docs: architecture, API reference, deployment
This makes it easier for users to find the right documentation.
* docs: consolidate documentation links with clear descriptions
Merge the two documentation links into a single "Documentation" section
with clear descriptions of each:
- User Guide: skill publishing, search, CLI usage
- Developer Docs: architecture, API reference, deployment
This makes it easier for users to find the right documentation.
* fix: include --home parameter in shutdown command
When starting with a custom --home directory, the generated shutdown
command now includes the same --home parameter to ensure it can find
the correct compose files.
