docs: add namespace claims guide

Adds a dedicated ClawHub namespace claims guide and routes existing claim references through it.

.github/CODEOWNERS

@@ -112,6 +112,7 @@
 /docs/api.md @openclaw/openclaw-secops @Patrick-Erichsen
 /docs/auth.md @openclaw/openclaw-secops @Patrick-Erichsen
 /docs/http-api.md @openclaw/openclaw-secops @Patrick-Erichsen
+/docs/namespace-claims.md @openclaw/openclaw-secops @Patrick-Erichsen
 /docs/security.md @openclaw/openclaw-secops @Patrick-Erichsen
 /docs/webhook.md @openclaw/openclaw-secops @Patrick-Erichsen
 /specs/deploy.md @openclaw/openclaw-secops @Patrick-Erichsen

docs/README.md

@@ -30,7 +30,8 @@ Reading order:
 6. `docs/skill-format.md`: skill bundle metadata and package shape.
 7. `docs/auth.md`: GitHub OAuth, API tokens, and CLI login.
 8. `docs/telemetry.md`: install telemetry and how to opt out.
-9. `docs/troubleshooting.md`: user-facing CLI, install, publish, update, and API fixes.
+9. `docs/namespace-claims.md`: org, brand, owner-handle, package-scope, skill-slug, and namespace ownership disputes.
+10. `docs/troubleshooting.md`: user-facing CLI, install, publish, update, and API fixes.
 
 Policy, API, and trust docs:
 
@@ -40,6 +41,7 @@ Policy, API, and trust docs:
 - `docs/security.md`: reporting ClawHub security issues and vulnerability disclosure policy.
 - `docs/security-audits.md`: user-facing security audit status, risk levels, findings, and interpretation.
 - `docs/moderation.md`: reports, moderation holds, hidden listings, bans, and account standing.
+- `docs/namespace-claims.md`: org, brand, owner-handle, package-scope, skill-slug, and namespace ownership claims.
 - `docs/content-rights.md`: copyright and other content rights requests involving ClawHub listings.
 
 Maintainer records:

docs/moderation.md

@@ -56,20 +56,14 @@ account action.
 ## Org and namespace claims
 
 Org, brand, package-scope, owner-handle, or namespace ownership disputes should
-use the
-[Org / Namespace Claim issue form](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml),
-not the in-product report flow or the account appeal form.
+use the [Org and Namespace Claims](./namespace-claims.md) process, not the
+in-product report flow or the account appeal form.
 
-Use that form when you need ClawHub staff to review non-sensitive proof that a
+Use that process when you need ClawHub staff to review non-sensitive proof that a
 namespace should be reserved, transferred, renamed, hidden, quarantined, aliased,
-or otherwise reviewed. Useful public evidence includes GitHub org or repo
-control, domain or official email-domain proof, package-registry scope control,
-trademark or brand evidence, source repo history, package history, and public
-project docs.
-
-Do not include secrets, private documents, private legal files, personal identity
-documents, API tokens, or DNS challenge tokens in a public issue. The issue form
-asks whether sensitive evidence needs a private staff channel.
+or otherwise reviewed. Do not include secrets, private documents, private legal
+files, personal identity documents, API tokens, or DNS challenge tokens in a
+public issue.
 
 ## Moderation holds
 

docs/namespace-claims.md

@@ -0,0 +1,97 @@
+---
+summary: "How to request ClawHub review for org, brand, owner-handle, package-scope, skill-slug, or namespace ownership disputes."
+read_when:
+  - Claiming an org, brand, package scope, owner handle, skill slug, or package namespace
+  - Resolving a namespace that is already claimed or reserved
+  - Deciding whether to use a report, appeal, or namespace claim
+title: "Org and Namespace Claims"
+sidebarTitle: "Org and Namespace Claims"
+---
+
+# Org and Namespace Claims
+
+ClawHub uses owner handles, org handles, skill slugs, plugin package names, and
+package scopes as public namespaces. If a namespace appears to belong to a
+real-world project, brand, package ecosystem, or organization but is already
+claimed, reserved, misleading, or disputed on ClawHub, ask staff to review it
+with the
+[Org / Namespace Claim issue form](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml).
+
+Use this path for public, non-sensitive ownership review. Do not use in-product
+reports or the account appeal form for namespace claims.
+
+## When to Open a Claim
+
+Open a namespace claim when you believe ClawHub staff should review whether a
+namespace should be reserved, transferred, renamed, hidden, quarantined, aliased,
+or otherwise changed because of real-world ownership.
+
+Examples include:
+
+- an org handle that matches your GitHub org, project, company, or community
+- a package scope such as `@example-org/*` that should only publish under the
+  matching ClawHub owner
+- a skill slug or plugin package name that appears to impersonate a project
+- a brand, trademark, project rename, or package history dispute
+- a deleted, inactive, or unreachable owner that blocks the rightful namespace
+  owner
+
+If the listing is unsafe, malicious, or misleading beyond the ownership dispute,
+also follow the relevant moderation or security guidance. The namespace claim
+form is for ownership review, not emergency vulnerability disclosure.
+
+## Before You File
+
+First confirm that you are publishing with the owner that matches the namespace.
+For plugin packages, scoped names such as `@example-org/example-plugin` must be
+published as the matching `example-org` owner.
+
+If you can manage the current owner, fix the namespace directly by publishing,
+renaming, transferring, hiding, or deleting the affected resource. Use a claim
+when you cannot manage the current owner or when staff needs to resolve a
+dispute.
+
+## Evidence to Include
+
+Use public, non-sensitive evidence. Helpful proof includes:
+
+- GitHub org, repo, release, or maintainer history
+- official project docs that name the namespace
+- domain or official email-domain proof
+- npm, PyPI, crates.io, or other package-registry scope control
+- trademark, brand, or project ownership evidence that is safe to discuss
+  publicly
+- source repository history, package history, or public rename notices
+- links to the disputed ClawHub owner, skill, plugin, package, or issue
+
+Explain what each link proves. Staff should be able to understand the
+relationship without needing private credentials or secrets.
+
+## What Not to Include
+
+Do not put secrets or private proof in a public GitHub issue. Do not include:
+
+- API tokens, signing keys, or credentials
+- DNS challenge tokens
+- private legal files or contracts
+- personal identity documents
+- private emails, private security reports, or confidential customer data
+
+The claim form asks whether sensitive evidence needs a private staff channel.
+Use that option instead of posting sensitive material publicly.
+
+## Possible Outcomes
+
+Depending on the evidence and risk, ClawHub staff may reserve a namespace,
+transfer ownership, rename a resource, hide or quarantine an existing listing,
+add an alias or redirect, ask for more proof, or decline the request.
+
+Namespace review does not guarantee that every matching name will be transferred.
+Staff weighs public evidence, existing usage, security risk, and user impact.
+
+## Related Docs
+
+- [Publishing](./publishing.md)
+- [Troubleshooting](./troubleshooting.md#publish-fails-because-a-namespace-is-claimed-or-reserved)
+- [Moderation and Account Safety](./moderation.md)
+- [Security](./security.md)

docs/publishing.md

@@ -71,8 +71,9 @@ not control.
 If you are the rightful owner of an org, brand, package scope, owner handle, or
 namespace that is already claimed or reserved on ClawHub, open an
 [Org / Namespace Claim issue](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml)
-with public, non-sensitive proof. Do not use the account appeal form for
-namespace claims.
+with public, non-sensitive proof. See
+[Org and Namespace Claims](./namespace-claims.md) for what to include and what
+to keep out of public issues.
 
 ### Before Publishing a Plugin
 
@@ -160,7 +161,8 @@ publish into a scope you cannot manage.
 If you do not have access to the current owner but believe your org, project, or
 brand is the rightful namespace owner, open an
 [Org / Namespace Claim issue](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml)
-with public, non-sensitive proof for staff review.
+with public, non-sensitive proof for staff review. See
+[Org and Namespace Claims](./namespace-claims.md) before filing.
 
 This protects org namespaces. A package named `@openclaw/dronzer` claims the
 `@openclaw` namespace, so only publishers with access to the `@openclaw` owner

docs/troubleshooting.md

@@ -98,8 +98,9 @@ matching `example-org` owner.
 If you believe your org, project, or brand is the rightful namespace owner but
 you cannot manage the current ClawHub owner, open an
 [Org / Namespace Claim issue](https://github.com/openclaw/clawhub/issues/new?template=org-namespace-claim.yml)
-with public, non-sensitive proof. Do not include secrets, private documents,
-DNS challenge tokens, or private legal files in the public issue.
+with public, non-sensitive proof. See
+[Org and Namespace Claims](./namespace-claims.md) for evidence guidance and what
+to keep out of public issues.
 
 ## `sync` says no skills were found