docs: redirect prebuilt archive references to pleaseai/spring-docs

[amondnet]

Summary

Update the plugin's README.md to reflect the new architecture decision: pre-converted Spring documentation archives now live in a dedicated content repository — pleaseai/spring-docs — rather than being released from this plugin repository.

This is a documentation-only change. No code, no behavior, no build changes.

Why

Earlier discussion landed on splitting the plugin code (this repo) from the generated Markdown content (new repo):

Reason	Outcome
Keep plugin repo small	git clone stays ~1 MB instead of growing with every Spring release
Independent release cadence	Docs can regenerate when upstream Spring publishes, without bumping the plugin
Tool-agnostic distribution	Archives become reusable by Cursor, Continue, RAG indexes, etc. — not Claude-Code-only
Conversion pipeline isolation	Antora/AsciiDoc machinery + its CI live with the content
Cleaner licensing surface	Apache-2.0 NOTICE/attribution lives next to redistributed content

Companion repo bootstrap (LICENSE, NOTICE, README, .gitignore, catalog.json skeleton): https://github.com/pleaseai/spring-docs (commit 2e52a67).

Changes (6 surgical edits, single file)

#	Section	Change
1	/spring:install step 5	Prebuilt-archive source now pleaseai/spring-docs releases
2	Plugin structure diagram	Drop nightly-build.yml (moved to spring-docs); reframe prebuilt/catalog.json as an offline mirror of spring-docs's catalog
3	"Prebuilt archives" intro	Explain rationale for the split (small plugin, independent cadence, tool-agnostic archives)
4	Manual fallback curl URL	pleaseai/spring/releases/spring-framework-6.2.1/... → pleaseai/spring-docs/releases/framework-6.2.1/... (also adopts new tag scheme <project>-<version>)
5	Licensing — Generated archives	Point NOTICE attribution + upstream-maintainer issues at spring-docs
6	Related projects	Add @pleaseai/spring-docs entry

Stats: +14 / −11 lines, README.md only.

Verification

$ grep -nP 'github\.com/pleaseai/spring(?!-docs)' README.md
(no matches)

$ grep -nc 'spring-docs' README.md
9

All 9 hits are intentional cross-references.

Follow-ups (not in this PR)

1. ADR-0002 — Write .please/docs/decisions/0002-docs-repo-split.md recording the split decision (referenced as "forthcoming" in the spring-docs README).
2. Pre-existing aside — Several README URLs use github.com/pleaseai/spring while the actual remote is pleaseai/spring-plugin. Pre-existing; not addressed here. Either rename the repo or fix the URLs in a follow-up.
3. Conversion pipeline & CI — Land in pleaseai/spring-docs as a separate track (scripts/, .github/workflows/matrix-build.yml, first framework-6.2.0 Release).

Type of change

• Documentation update
• Bug fix
• New feature
• Breaking change

---

Summary by cubic

Update README to point all prebuilt Spring docs references to pleaseai/spring-docs and clarify the manual fallback tag scheme. Docs only; no code or behavior changes.

• Docs
  • Updated install step, plugin structure diagram, and “Prebuilt archives” section to reference pleaseai/spring-docs.
  • Switched offline fallback curl URL to pleaseai/spring-docs and clarified tag scheme to <component>-<version> (e.g., framework-6.2.1); asset filenames keep the spring- prefix.
  • Reframed prebuilt/catalog.json as an offline mirror and replaced nightly-build.yml with ci.yml.
  • Moved licensing/NOTICE guidance and maintainer issue links to pleaseai/spring-docs, and added @pleaseai/spring-docs to Related projects.

^{Written for commit bfd8adf. Summary will update on new commits.}

[gemini-code-assist]

Code Review

This pull request updates the documentation to reflect the migration of prebuilt Markdown archives to a dedicated repository, pleaseai/spring-docs. Key changes include updating repository links, clarifying the separation of content from code, and adjusting the directory structure description to treat local catalogs as offline fallbacks. Feedback was provided to clarify the tag naming convention in the manual download example to prevent ambiguity regarding the spring- prefix in release tags versus asset filenames.

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="README.md">

<violation number="1" location="README.md:273">
P3: The hint `(tag scheme: <project>-<version>)` is ambiguous: the example tag is `framework-6.2.1` (no `spring-` prefix) while the asset filename is `spring-framework-6.2.1.tar.gz` (with prefix). Users extrapolating to other components (e.g., Spring Boot) won't know whether the tag should be `boot-3.2.0` or `spring-boot-3.2.0`. Consider clarifying that the tag drops the `spring-` prefix, e.g., `(tag scheme: <component>-<version>, e.g., framework-6.2.1)`.</violation>
</file>

Architecture diagram

sequenceDiagram
    participant Plugin as Spring Plugin (pleaseai/spring-plugin)
    participant DocsRepo as pleaseai/spring-docs
    participant GitHub as GitHub Releases
    participant SpringUpstream as docs.spring.io
    participant Cache as Local Cache (~/.cache/pleaseai-spring/archives/)

    Note over Plugin,DocsRepo: Architecture: Plugin code and docs content are now separate repos

    Plugin->>Plugin: /spring:install runs
    Plugin->>Plugin: Resolve Spring component versions from BOM

    alt Prebuilt archive exists in spring-docs
        Plugin->>GitHub: Check pleaseai/spring-docs releases for <project>-<version> archive
        GitHub-->>Plugin: Release asset URL
        Plugin->>Cache: Download and extract archive (~3 seconds)
        Cache-->>Plugin: Extracted Markdown skills
    else No prebuilt archive
        Plugin->>SpringUpstream: Fetch docs from docs.spring.io
        SpringUpstream-->>Plugin: HTML documentation
        Plugin->>Plugin: Convert Antora HTML to Markdown (~30-60 seconds)
    end

    Plugin->>Plugin: Install into .claude/skills/spring-<component>/
    Plugin->>Plugin: Generate SKILL.md

    Note over Plugin,DocsRepo: Offline fallback flow

    alt Network unreachable
        User->>Cache: Pre-stage archive (downloaded from spring-docs on connected machine)
        Cache-->>Plugin: Use local archive from cache
    end

    Note over DocsRepo,GitHub: Content repo maintains its own release cycle

    DocsRepo->>DocsRepo: Build archives nightly from upstream Spring releases
    DocsRepo->>GitHub: Publish release with tag <project>-<version>
    GitHub-->>GitHub: Host archive with NOTICE (Apache-2.0 license attribution)

Loading

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}