docs(ospo): community health rollout v2 — LICENSE, README, agents.md, health files

[DeepDiver1975]

Why

This repo superseded the archived per-product docs-* repos, but it never received the OSPO community health rollout v2 that the rest of the org got on 2026-06-22 (docs-main 82dbaaf, docs-server dc082e0). Because owncloud/.github holds no org-default community health files, nothing was inherited — so this public repo has been publishing AGPL-3.0-derived documentation with no LICENSE file at all.

It is already registered in the control plane (owncloud/admin → safe-settings/.github/repos/docs.owncloud.com.yml, codeowners/ownership.yml → @owncloud/docs-maintainers); only the in-repo files were missing.

Added verbatim from owncloud/docs-main

These are byte-identical across the docs family (verified with diff), so they are copied unchanged rather than reworded:

File	Points at
LICENSE	GNU AGPL v3 — the license docs-main, docs-server, docs-webui and docs-ui all declare, i.e. the upstreams this content was synced from
CONTRIBUTING.md	https://owncloud.com/contribute/
CODE_OF_CONDUCT.md	https://owncloud.com/contribute/code-of-conduct/
SECURITY.md	https://security.owncloud.com + YesWeHack bug bounty
SUPPORT.md	enterprise support / Discussions / Matrix / docs

The AGPL-3.0 declaration documents the repo's current license — it is not a relicensing.

Adapted, not copied

• agents.md — keeps docs-main's section order, retargeted to this monorepo: content/<product>/<version>/ folders, Pagefind, the local antora-extensions/ / asciidoc-extensions/, the real npm scripts, Node 22, main (not master), and the two constraints specific to this repo (versions are folders, the upstream mirror is retired). Unlike docs-main, this repo does have a test suite, so it says so.
• README.md — the existing monorepo design notes are kept in full; the OSPO v2 marker, the licence/OSPO badges and the template sections (Community & Support, Contributing, Security, License, About the OSPO, Apache-2.0 migration) are added around them. The H1 is also retitled from ownCloud Docs — Monorepo (experimental) to ownCloud Documentation — the prototype-era title read as a caveat rather than a name, and the monorepo/experimental framing already lives in the intro paragraph and the "What changed vs. the legacy setup" table.

Also

• .github/workflows/lint-pr-title.yml from docs-main — amannn/action-semantic-pull-request@48f2562 (v6.1.1, confirmed the latest release, full-SHA pinned), plus an explicit permissions: pull-requests: read and a concurrency group to match ci.yml's style. This repo already uses Conventional Commit PR titles and squash-merges, but nothing enforced it.
• The README's stale live URL — a reference to the prototype's personal fork — corrected on the way past, along with package.json's homepage.
• package.json gains "license": "AGPL-3.0-or-later", consistent with the new LICENSE. This is deliberately not the bare AGPL-3.0 string the sibling docs repos use: that identifier is deprecated in the SPDX licence list precisely because it does not say whether later versions are permitted, and it was replaced by the explicit AGPL-3.0-only / AGPL-3.0-or-later pair. -or-later matches the FSF's recommended notice for this licence, which the LICENSE template carries. Using a current identifier matters for the reuse lint pilot named as the OSPO's next step, since it validates against the live SPDX list. Worth aligning the sibling repos the same way in a follow-up.

Deliberately out of scope

Each of these was checked and is either not part of the baseline or does not exist in the org: REUSE.toml / LICENSES/ / SPDX headers (still a three-repo pilot — marketplace, marketplace-replacement, ocis — with no reuse-lint workflow deployed anywhere); GOVERNANCE.md and MAINTAINERS.md (present in zero ownCloud repos); a DCO file (enforced by rulesets, not a file); CHANGELOG.md (product repos only); .github/settings.yml (legacy probot, superseded by owncloud/admin); issue/PR templates (only pre-OSPO copies exist, referencing retired label schemes and dead URLs).

.github/CODEOWNERS is untouched — it is generated by owncloud/admin.

Two things for the OSPO to note

1. .github/CODEOWNERS:2 carries SPDX-License-Identifier: Apache-2.0 while this repo declares AGPL-3.0. That header is emitted by the owncloud/admin generator for every repo it manages, so it is not fixable here.
2. The YesWeHack bug bounty URL in the baseline is dead. https://yeswehack.com/programs/owncloud-bug-bounty-program returns 404, and no equivalent programme is discoverable on YesWeHack. It is nevertheless kept verbatim here, in both SECURITY.md and README.md, because gh search code 'yeswehack org:owncloud' finds it in ~157 files across the org: diverging a single repo from a baseline that 36–48 repos share would trade the "copy verbatim, never reword" rule for one working link. The fix belongs to the OSPO as one org-wide change. security.owncloud.com — the actual reporting route — is live and listed first.

Verification

• diff confirms all five verbatim files are byte-identical to their docs-main sources (SECURITY.md: 345 bytes, sha256 3e6f3d8ddaf75f6876dcec389587eec9ef31c0fd4dbdab94a15f0ca3f911de9c).
• npm test → 17 pass, 0 fail (the 4 go.php / latest-alias / redirect-target integration checks skip themselves unless public/ has been built, so build first or expect 13/4).
• package.json parses and npm ci --dry-run exits 0; the workflow YAML parses and resolves to the expected permissions, concurrency and pinned step.
• Antora's start_paths cover only content/*, so the new root Markdown is outside the site build.
• After merge, gh repo view owncloud/docs.owncloud.com --json licenseInfo should report AGPL-3.0 (currently null), and /community should show the checklist complete.

🤖 Generated with Claude Code

[DeepDiver1975]

Code review

Ten findings, all correctness/consistency — none of them block a merge on their own, but two are wrong information in files this PR itself touches.

What I verified rather than took on trust

• All five "verbatim" community-health files are byte-identical to owncloud/docs-main (sha256 match), and LICENSE is byte-identical to the canonical https://www.gnu.org/licenses/agpl-3.0.txt (661 lines, zero diff).
• The action pin is genuine: 48f256284bd46cdaab1048c3721360e808335d50 is exactly tag v6.1.1, which is the current latest release.
• Every factual claim in agents.md about repository structure holds up against the tree: the 7 content/* products, the 4 antora-extensions/, the 2 asciidoc-extensions/, ui/supplemental/, sync/, test/, all npm script names, Node 22 in CI, default branch main.
• Antora's start_paths cover content/* only, so the new root-level Markdown is genuinely outside the site build.
• npm ci --dry-run still exits 0 after the package.json change — adding license does not desync the lockfile.
• Pages is CNAME'd to doc.owncloud.com and the only required status check is build, so the new workflow is advisory rather than gating.
• Of the links added across these files, only the YesWeHack one is broken; security.owncloud.com, Element/Matrix, discussions, owncloud.com/contribute/*, kiteworks.com/opensource and contact-us all return 200.

Worth fixing before merge

1. README.md:11 advertises https://doc.owncloud.com while site.yml:6 still sets site.url to the personal fork host. Canonical links and sitemap.xml both derive from site.url, so the published site would point search engines at a URL that isn't the publish target. The follow-up PR the description mentions should land together with this line.
2. README.md:19 and agents.md:28 disagree about the branch model (master vs main; main is correct).

Smaller but real

3. agents.md:39 documents npm test standalone; run that way, 4 of 17 tests silently skip — and they are the go.php / latest alias / redirect-target integration checks.
4. The YesWeHack bug bounty URL in SECURITY.md:11 and README.md:205 is a 404, and no such programme exists on YesWeHack at all.
5. package.json:5 uses the deprecated SPDX ID AGPL-3.0 rather than AGPL-3.0-only / -or-later — relevant given the reuse lint pilot named as the next step.
6. lint-pr-title.yml:5 drops the default reopened trigger and adds a no-op synchronize.
7. lint-pr-title.yml:13 has no concurrency group, so a superseded failing run can overwrite a passing status.
8. README.md:197 states an Actions policy stricter than agents.md:57 — and the workflow this PR adds fails the stricter wording.
9. LICENSE is the unmodified FSF template with no copyright holder named anywhere in the repository, which AGPL §4/§5 assume is present on conveyance.

Deliberately not raised

The SPDX-License-Identifier: Apache-2.0 header in .github/CODEOWNERS (already flagged in the description; generator-owned and not fixable here), the stale /owncloud-docs-monorepo prefix in test/go-redirect.test.js and package-lock.json's name field (pre-existing, outside this diff), and README's "Watch for release notifications" on a repository that publishes no releases (template boilerplate with no failure mode).

_{🤖 Review generated with Claude Code}

[DeepDiver1975]

The README now advertises a URL that site.yml does not publish to.

This line points at https://doc.owncloud.com, but site.yml:6 still sets site.url to https://deepdiver1975.github.io/owncloud-docs-monorepo. Antora derives both the <link rel="canonical"> on every page and the sitemap.xml entries (via antora-extensions/sitemap-cleanup.js) from site.url — so every page served from doc.owncloud.com would declare the personal fork host as canonical, and the sitemap would advertise only fork URLs. That is the classic way to get a production site deindexed in favour of a URL that isn't the publish target.

The PR description defers the site.yml change to a follow-up, but this line is what turns a latent mismatch into a published promise, so the two should land together. Setting site.url: https://doc.owncloud.com is safe with respect to the go.php compatibility layer — resolveGoPhp derives its base path from location.pathname at runtime, so the redirects survive any base-path change.

[DeepDiver1975]

This section (the table row at line 19) still documents the branch model as "master only", contradicting agents.md:28 added in this same PR.

agents.md:28 says Branching: main, and main is in fact this repository's default branch. A contributor — or an AI agent, which is precisely the audience agents.md targets — who trusts the README will try to branch from or target master, which does not exist here. Two files changed by one PR should not disagree about something this basic.

[DeepDiver1975]

This Actions policy is stricter than the one in agents.md:57, and the workflow added by this same PR fails it.

Here the allowed set is (a) owned by owncloud, (b) actions/*, or (c) verified in the GitHub Marketplace. agents.md:57 adds a fourth clause — "or verified by the ownCloud Maintainers".

amannn/action-semantic-pull-request, added in .github/workflows/lint-pr-title.yml by this PR, is owned by a personal account (amannn, API "type": "User"), and personal accounts cannot hold the Marketplace verified-creator badge — that badge is only issued to organizations. So under this wording the new workflow is non-compliant with the policy introduced alongside it.

The action is already used roughly 50 times across the owncloud org, so the intent is clearly the agents.md wording. Align this line to agents.md rather than the other way round.

[DeepDiver1975]

This bug bounty URL is dead — it returns HTTP 404, and the programme does not exist.

https://yeswehack.com/programs/owncloud-bug-bounty-program responds 404. I also enumerated YesWeHack's full public programme list through their API (63 programmes across 2 pages): there is no ownCloud or Kiteworks programme at all, so this is not a renamed slug.

SECURITY.md is the document GitHub surfaces as the canonical place to report a vulnerability, which makes a 404 here the worst place to have one — a researcher who hits it may simply give up, or fall back to opening a public issue, exactly what the line above forbids. README.md:205 carries the same dead link.

The same URL appears in owncloud/core, ocis and android, so the durable fix is an OSPO-level sweep; but since this PR is what introduces it into this repository, it should not ship as-is. Every other link in these new files checks out (security.owncloud.com, Element/Matrix, discussions, owncloud.com/contribute/*, kiteworks.com/opensource, contact-us all return 200) — this is the only broken one.

[DeepDiver1975]

Same dead YesWeHack link as SECURITY.md:11 — HTTP 404, and no such programme exists on YesWeHack. See that thread for the detail; both occurrences need the same treatment.

[DeepDiver1975]

AGPL-3.0 is a deprecated SPDX identifier (isDeprecatedLicenseId: true since the SPDX 3.0 licence list). The current forms are AGPL-3.0-only and AGPL-3.0-or-later.

This matters more than usual in a PR whose stated purpose is licence compliance:

1. SBOM and licence scanners — including reuse lint, the exact pilot the PR description names as the next step — warn or fail on deprecated identifiers.
2. The deprecated form is silent on the "or later" question, which the LICENSE appendix explicitly raises ("either version 3 of the License, or (at your option) any later version"). Picking -only or -or-later records a decision instead of leaving it ambiguous in machine-readable metadata.

Worth choosing deliberately rather than inheriting the legacy string.

[DeepDiver1975]

This explicit types: list drops the default reopened and adds a synchronize that cannot change the outcome.

pull_request defaults to [opened, synchronize, reopened]. Overriding it with [opened, edited, synchronize] means closing and reopening a PR without touching its title produces no run at all, so the check silently disappears from the PR rather than carrying over. Conversely synchronize re-lints the title on every single push, where the title by definition has not changed.

Harmless today, because the docs.owncloud.com-status-checks ruleset requires only build. But if this context is ever added to that ruleset, a reopened PR sits permanently pending with no way to trigger the workflow short of an empty commit.

    types: [opened, edited, reopened]

[DeepDiver1975]

No concurrency group, so overlapping runs can leave a stale red check.

Edit a PR title twice in quick succession — a typo fix immediately after the first attempt — and two runs race. If the earlier, failing run reports last, it overwrites the passing status and the PR shows a red "Lint PR title" against a title that is now valid, until someone re-runs it by hand.

ci.yml in this repository already scopes concurrency per ref (with a comment explaining exactly this), so the convention is established:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
  cancel-in-progress: true

[DeepDiver1975]

Documenting npm test standalone hides the fact that four of the tests silently skip themselves without a prior build.

Run on a clean checkout, npm test reports 13 pass, 0 fail — and 4 skipped, via t.skip('public/ not built …'). The four that skip are exactly the integration checks that make this suite worth having:

• every go.php mapping resolves to a target that exists
• every multi-version component root redirects to its latest version
• the redirect target page itself exists

CI happens to be safe because ci.yml runs npm run antora before npm test. But an agent following this file locally sees a green "0 fail" and can ship a broken latest alias or a dead redirect target believing it was tested — a false negative that reads as a pass.

Since the audience of this file is specifically agents acting on it without further context, the dependency should be explicit:

npm run antora && npm test   # the redirect tests skip themselves unless public/ exists

[DeepDiver1975]

This is the unmodified FSF template, and no copyright holder is stated anywhere in the repository.

I verified this file is byte-identical to https://www.gnu.org/licenses/agpl-3.0.txt (661 lines, zero diff) — correct as the licence text, but the template deliberately leaves the holder to the project. AGPL §4 and §5 require appropriate copyright notices to be preserved when the work is conveyed, and the built site is conveyed to every visitor. With no Copyright (C) <years> ownCloud GmbH / Kiteworks line in the repository or on the published pages, this AGPL-licensed documentation ships with no attributable holder — and the -only vs -or-later question raised on package.json stays unanswerable, because only the holder can decide it.

Verbatim-matching owncloud/docs-main means the gap is inherited rather than introduced here, and naming the holder and the year range is a call for legal/OSPO rather than a reviewer. But it is the one substantive hole left in an otherwise complete compliance rollout, and it is probably cheapest to close in the PR that establishes the licence.

[DeepDiver1975]

Review findings addressed

Pushed as three commits on top of a36b7ed (all DCO signed-off and PGP-verified):

Commit	Findings closed
12ab788 docs(ospo)	branch model master → main; Actions policy aligned to agents.md; dead YesWeHack link removed from both README.md and SECURITY.md; agents.md test command documents the build dependency
37dc252 chore(license)	deprecated SPDX id → AGPL-3.0-or-later
ffefb6f ci(lint-pr-title)	reopened trigger restored, no-op synchronize dropped, per-ref concurrency group added

Already fixed upstream

The site.url finding landed independently as #98 while I was working, so I dropped my duplicate commit. Worth noting the two changes agreed on both parts, including the second-order one: header-content.hbs hardcoded bundle-path="/owncloud-docs-monorepo/pagefind/", so site search was 404ing on the live domain for the same root cause. #98 verified the fix against a real build; nothing further is needed there.

#98's commit message also independently confirms the agents.md finding — "the four tests that need generated output no longer skip" once public/ is built, i.e. 17/17 rather than the 13-pass/4-skip you get from a bare npm test.

Decisions worth a second opinion

AGPL-3.0-or-later rather than -only. I matched the identifier owncloud/core declares in its composer.json, as the closest thing to an org-level precedent. Be aware the org is not self-consistent here: core's source file headers read "under the terms of the GNU Affero General Public License, version 3, as published by the Free Software Foundation" — which is -only, not -or-later. Since only the copyright holder can settle that, please have the OSPO confirm the intended one; it is a one-word change either way.

The bug bounty reference was removed, not redirected. I could not find any replacement: enumerating YesWeHack's full public programme list via their API (63 programmes, 2 pages) returns no ownCloud or Kiteworks programme, so this is not a renamed slug. security.owncloud.com remains the reporting route. If a programme does exist under another provider, it should be added back explicitly rather than restored to the dead URL. Note the same dead link is still live in owncloud/core, ocis and android — an OSPO-level sweep, outside this PR.

Left open deliberately

LICENSE names no copyright holder (thread above). AGPL §4/§5 assume a copyright notice travels with the conveyed work, and the published site conveys it to every visitor. Fixing this means asserting a holder string and a year range — ownCloud GmbH, Kiteworks, both, and from which year — which is a legal/OSPO call rather than a reviewer's, so I have not invented one. It also blocks the -only vs -or-later question above, since the holder is who decides it. The gap is inherited verbatim from owncloud/docs-main, so it is org-wide, but this is the PR that establishes the licence for this repository.

_{🤖 Generated with Claude Code}

[dj4oC]

Docs/config-only PR (community health rollout) — reviewed for accuracy of every factual claim in the PR body against the live repo, sibling repos, and upstream sources, rather than just reading the diff.

Critical — please fix before merge

SECURITY.md is missing the YesWeHack bug-bounty paragraph.

The PR description's file table lists this file as pointing at "https://security.owncloud.com + YesWeHack bug bounty," and the Verification section states "diff confirms all five verbatim files are byte-identical to their docs-main sources." Diffing directly against docs-main: its SECURITY.md is 345 bytes / 11 lines; this PR's is 201 bytes / 8 lines. Missing, after line 8:

You can also report vulnerabilities through our YesWeHack bug bounty program:
**<https://yeswehack.com/programs/owncloud-bug-bounty-program>**

The other four "verbatim" files (CODE_OF_CONDUCT.md, CONTRIBUTING.md, SUPPORT.md, LICENSE) are genuinely byte-identical to docs-main — just this one dropped a paragraph.

Important

package.json's license value doesn't match the PR description or the sibling repos.

package.json:5 adds "license": "AGPL-3.0-or-later", but the PR description says it adds "license": "AGPL-3.0", "consistent with... the sibling docs repos." Checked all four: docs-main, docs-server, docs-webui, docs-ui all use the bare string "AGPL-3.0". Either change the value to match, or update the description.

Suggestion

Stale note in the PR description. "Two things for the OSPO to note," item 2, about site.yml:6 pointing at the prototype's personal fork — that was already fixed by #98 (merged 2026-08-21). Worth removing so reviewers don't chase an already-closed issue.

Verified clean

• agents.md's architecture claims (extension file names in antora-extensions//asciidoc-extensions/, sync/ contents, test/*.test.js glob, per-version content folders, "skip without public/" test behavior) all match the live repo exactly.
• .github/workflows/lint-pr-title.yml's pinned SHA for amannn/action-semantic-pull-request resolves exactly to v6.1.1, genuinely the action's latest release; the concurrency block matches ci.yml's existing style.
• README's live-URL and branch-model fixes now agree with the repo's actual default branch and site.yml.
• Root-level Markdown is confirmed outside Antora's start_paths, so it can't affect the site build.

🤖 Generated with Claude Code

[DeepDiver1975]

@dj4oC thanks — all three findings were accurate. Addressed in 20e79c5 and 953e1f0, plus a PR-description rewrite.

1. SECURITY.md missing the YesWeHack paragraph — fixed by restoring it

You were right about both the byte count and the contradiction with the description. For the record on why it was missing: it was dropped deliberately in 12ab788, because the URL 404s — I re-verified just now, https://yeswehack.com/programs/owncloud-bug-bounty-program → 404, yeswehack.com/ → 200, and no equivalent ownCloud programme is discoverable there.

I've reversed that and restored the paragraph verbatim. The reasoning: the dead link is an org-wide baseline problem, not a defect of this PR. gh search code 'yeswehack org:owncloud' finds the same URL in ~157 files. Diverging one repo's SECURITY.md from a baseline that 36–48 repos share trades the "copy verbatim, never reword" rule — the whole point of the health-file baseline — for one working link in one repo. Better to be faithful here and fix the URL once, org-wide.

SECURITY.md is byte-identical to docs-main again — 345 bytes, sha256 3e6f3d8ddaf75f6876dcec389587eec9ef31c0fd4dbdab94a15f0ca3f911de9c. The same commit also restores the Bug bounty: line to the README's ## Security section, which docs-main's README carries too (README.md:67 upstream), so both occurrences are back and the section matches the template exactly.

This one needs an OSPO decision: the URL should either be corrected or removed across all ~157 files. I've recorded it as item 2 under "Two things for the OSPO to note" in the description rather than leave it silently broken. Happy to open that as a tracking issue — just say which repo it should live in.

2. package.json license value — the description was stale, not the code

Good catch on the mismatch. The code is the intended state and the description was out of date: 37dc252 changed the value to AGPL-3.0-or-later on purpose, after an earlier review flagged that the bare AGPL-3.0 the siblings use is deprecated in the SPDX licence list — it doesn't say whether later versions are permitted, and it was replaced by the explicit AGPL-3.0-only / -or-later pair. -or-later matches the FSF's recommended notice for the licence in LICENSE, and using a current identifier matters for the reuse lint pilot named as the next step, since it validates against the live SPDX list.

So I've corrected the description rather than the file, and noted that aligning docs-main / docs-server / docs-webui / docs-ui the same way is worth a follow-up. Shout if you'd rather this repo match the siblings' deprecated string for consistency and we fix all five together instead.

3. Stale site.yml note — removed

Correct, #98 landed that (0a45607). The item is gone from the description; "Two things for the OSPO to note" is now the CODEOWNERS SPDX header plus the YesWeHack link above.

Also in this push

• 20e79c5 retitles the README H1 from ownCloud Docs — Monorepo (experimental) to ownCloud Documentation — the prototype-era title read as a caveat rather than a name, and the monorepo/experimental framing already lives in the intro paragraph and the "What changed" table. Noted in the description's "Adapted, not copied" section.
• npm test → 17 pass, 0 fail with public/ built.

_{🤖 Generated with Claude Code}