[Feature]: Improve newcomer documentation experience and align docs homepage with README

Start by reviewing the documentation homepage, README “Start in 5 minutes,” Kotlin and Java getting-started guides, and the docs build and dependency-version configuration. Then verify the correct SKaiNET-transformers and Minerva links, and find pages rendered as “Untitled :: SKaiNET.” Done means the homepage and README present consistent newcomer paths, current getting-started versions are clear, page titles are meaningful, and relevant examples are validated; the issue leaves key content-sharing and version-source decisions open.

🧠 D: DOCUMENT — Problem & Opportunity

What is the problem, limitation, or opportunity? Why does this matter for SKaiNET?

SKaiNET already has strong technical documentation, but the first-time experience is still relatively difficult for developers who are discovering the project.

The documentation homepage introduces many technical concepts and implementation details immediately, while the main repository README currently provides a clearer, more goal-oriented entry point through its “Start in 5 minutes” section.

This creates two related problems:

1. A newcomer may have difficulty understanding SKaiNET's core value proposition before being exposed to implementation terminology.
2. The documentation homepage and repository README provide different newcomer experiences and can drift out of sync.

The goal is to make both entry points communicate the same high-level message, expose the same primary getting-started paths, and help a new developer reach a successful first example with minimal friction.

Current limitations

Homepage introduces too much terminology too early

The opening documentation introduces many concepts and implementation details at once, including:

• GGUF
• SafeTensors
• ONNX
• quantization formats
• StableHLO
• Minerva
• MCU targets
• CPU / GPU / NPU targets

These details are useful and should remain available, but presenting them before the core user-facing value proposition increases cognitive load for first-time visitors.

The homepage should first answer:

• What is SKaiNET?
• Who is it for?
• What can I build with it?
• How can I try it in a few minutes?

Technical details can follow afterward.

Getting-started paths are not prominent enough

Newcomers should immediately see clear paths based on what they want to accomplish, for example:

• Kotlin Getting Started
• Java Getting Started
• Tensor operations
• Train a neural network
• Run local / GGUF models
• Edge / MCU deployment

The repository README already has a useful goal-oriented “Start in 5 minutes” structure that can be reused or closely mirrored on the documentation homepage.

Documentation homepage and README are not sufficiently aligned

The README currently provides a stronger first-impression experience than the documentation homepage.

A developer arriving through either surface should see:

• the same high-level SKaiNET value proposition
• the same primary getting-started paths
• the same recommended first steps
• consistent links to related SKaiNET projects and deployment paths

The README and documentation homepage do not need to contain identical content, but their newcomer-facing structure and primary calls to action should remain aligned.

Dependency versions are inconsistent across current documentation

Getting-started examples currently reference different SKaiNET versions.

For a newcomer, this makes it difficult to know whether an example is current, compatible, or expected to compile.

Documentation representing the current getting-started experience should use a consistent version from a single source of truth where practical.

Older versions can remain in historical, migration, or release-specific documentation when intentional and clearly identified.

Some documentation pages have incomplete titles

Some pages currently render with titles such as:

Untitled :: SKaiNET

Tutorial and guide pages should have meaningful titles for:

• browser tabs
• search results
• navigation
• link previews
• perceived documentation quality

SKaiNET-transformers is difficult for newcomers to discover

Developers interested in GGUF and local LLM functionality need an obvious route from both the main documentation and README to SKaiNET-transformers.

A newcomer should not need to already know that this functionality belongs to a related project.

Summary (1–2 sentences):

Improve SKaiNET's first-time developer experience by making the documentation homepage outcome-oriented, exposing clear getting-started paths, and aligning those paths with the repository README. Also remove avoidable onboarding friction caused by inconsistent versions, incomplete page titles, and unclear links to SKaiNET-transformers and Minerva.

---

🔍 A: ASSESS — Feasibility & Impact

✔️ Feasibility

Most of the proposed work is documentation and information-architecture work rather than a change to SKaiNET's runtime or public APIs.

The main changes are expected to involve:

• documentation homepage content
• README content
• navigation / CTA links
• page metadata
• documentation version handling
• validation of getting-started examples

The basic homepage and README restructuring should be straightforward.

The potentially larger piece is establishing a reliable single source of truth for dependency versions and/or shared newcomer-facing content. The appropriate implementation depends on how the current documentation build is structured.

No core engine architecture changes should be required.

✔️ Expected Impact

This should significantly improve the experience of developers evaluating SKaiNET for the first time.

Expected benefits include:

• faster understanding of what SKaiNET is for
• clearer paths from discovery to first successful example
• less cognitive load on the documentation landing page
• stronger discoverability of Kotlin and Java onboarding
• stronger discoverability of SKaiNET-transformers
• stronger discoverability of Minerva / edge deployment
• less confusion caused by inconsistent dependency versions
• greater confidence that getting-started examples are current
• a more consistent experience between GitHub and the documentation site
• reduced risk of README and documentation onboarding flows drifting independently

This does not remove technical depth. It changes the order in which that depth is presented.

Newcomers first get a clear entry point; advanced users can still access the full engine, compilation, format, quantization, and deployment documentation.

✔️ Risks / Constraints

Content duplication

Mirroring onboarding content between the README and documentation homepage may introduce duplication and future drift.

Possible mitigations:

• generate both from a shared source/snippet where practical
• define one surface as canonical and explicitly require updates to the other
• add lightweight documentation checks if appropriate

Over-simplifying the homepage

The homepage should remain technically accurate and should not hide SKaiNET's broader capabilities.

The goal is progressive disclosure:

1. explain the user-facing value
2. provide clear starting points
3. expose detailed technical capabilities afterward

Version synchronization

Automatically sharing dependency versions across all documentation may require build-system work.

The scope should focus first on documentation intended to represent the current getting-started experience.

Historical, migration, benchmark, or version-specific examples do not necessarily need to use the current version.

Related-project boundaries

Links to SKaiNET-transformers and Minerva should make project boundaries clearer rather than suggesting that all functionality exists directly in the core SKaiNET module.

✔️ Dependencies

This work depends primarily on the existing:

• SKaiNET documentation structure
• documentation build pipeline
• repository README
• Kotlin Getting Started tutorial
• Java Getting Started tutorial
• SKaiNET-transformers project/documentation
• Minerva documentation
• dependency/version configuration used by documentation examples

No new third-party runtime dependency is expected.

---

📚 R: RESEARCH — What Must Be Understood First?

Before implementation, review how newcomer-facing documentation is currently generated and determine the simplest way to keep the README and documentation homepage aligned.

Research Tasks

• Review the current documentation homepage structure and identify content that should remain above/below the initial newcomer section
• Review the README “Start in 5 minutes” section and identify which paths should become the shared primary CTAs
• Verify the current Kotlin Getting Started entry point
• Verify the current Java Getting Started entry point
• Identify the correct SKaiNET-transformers entry point for GGUF / local model users
• Identify the correct Minerva entry point for Edge / MCU users
• Audit current getting-started documentation for SKaiNET dependency versions
• Determine whether current documentation versions can come from a shared Gradle/project property or another single source of truth
• Identify documentation pages currently rendered as Untitled :: SKaiNET
• Check whether README/docs content can share snippets or generated data without making the documentation build unnecessarily complex
• Identify which examples are intended to track the current release versus intentionally documenting older/version-specific behavior
• Verify which getting-started examples are already compiled/tested in CI and which still require validation

Open Questions

Should the README or documentation homepage be considered the canonical source for newcomer-facing CTAs, or should both be generated from shared content?

Can the current SKaiNET version used in documentation examples be injected automatically from the build configuration?

Should the “Start in 5 minutes” section be shared verbatim, or should README and docs use different presentation while sharing the same destinations?

Which SKaiNET-transformers page should be the primary CTA for users whose goal is “Run a local / GGUF model”?

Which Minerva page should be the primary CTA for users whose goal is “Deploy to Edge / MCU”?

Should documentation CI validate only code snippets used in getting-started tutorials, or is broader snippet validation already available?

---

🛠️ C: CODE — Implementation Plan

Proposed Homepage / README Direction

Use a short, benefit-oriented introduction before describing engine internals.

For example:

Build and run AI models in Kotlin and Java — from JVM development to native and edge deployment.

SKaiNET provides tensors, neural-network APIs, model loading, training, quantization, and portable compilation while staying within the Kotlin ecosystem.

The final wording can change during review. The important requirement is that the first paragraph communicates the user-facing value before presenting implementation details.

Immediately follow it with a prominent “Start in 5 minutes” or “Choose your goal” section.

For example:

I want to…	Start here
Use SKaiNET from Kotlin	Kotlin Getting Started
Use SKaiNET from Java	Java Getting Started
Learn basic tensor operations	Tensor tutorial
Train a neural network	Training tutorial
Run a local / GGUF model	SKaiNET-transformers
Deploy to edge / MCU targets	Minerva / Edge guide

The README and documentation homepage should expose the same primary paths even if the visual presentation differs.

Development Tasks

Homepage & README

• Rewrite the documentation homepage introduction around user outcomes rather than engine internals
• Add a prominent “Start in 5 minutes” / “Choose your goal” section to the documentation homepage
• Align the main README with the same high-level value proposition
• Keep the same primary newcomer CTAs on both surfaces
• Link Kotlin Getting Started directly from the documentation homepage
• Link Java Getting Started directly from the documentation homepage
• Keep equivalent Kotlin and Java links prominent in the README
• Add a clear local LLM / GGUF path to SKaiNET-transformers
• Add a clear Edge / MCU deployment path to Minerva

Documentation consistency

• Audit current getting-started examples for dependency-version inconsistencies
• Synchronize versions across documentation representing the current getting-started experience
• Use a single source of truth for the current documentation dependency version where practical
• Preserve intentionally older/version-specific examples where appropriate and clearly identify them
• Fix all currently known pages rendering as Untitled :: SKaiNET
• Review the complete getting-started navigation from the perspective of a first-time developer

Validation

• Verify that Kotlin Getting Started compiles and runs using the documented version
• Verify that Java Getting Started compiles and runs using the documented version
• Verify other primary getting-started examples linked from the homepage
• Check all newcomer-facing links from both README and documentation homepage
• Confirm SKaiNET-transformers and Minerva destinations are clear and current

Keeping README and docs aligned

• Decide whether README/docs onboarding content should use a shared source/snippet or a documented canonical source
• Implement the selected synchronization approach
• Document the process so future onboarding changes update both entry points
• Add automated validation where practical without unnecessarily complicating the documentation build

Acceptance Criteria

• A developer unfamiliar with SKaiNET can understand its main purpose within 30 seconds of opening either the documentation homepage or main README
• The documentation homepage communicates the user-facing value of SKaiNET before presenting detailed implementation terminology
• A newcomer can identify an appropriate getting-started path without already knowing SKaiNET-specific terminology
• Kotlin Getting Started is directly discoverable from the newcomer-facing section
• Java Getting Started is directly discoverable from the newcomer-facing section
• Local model / GGUF users can clearly discover SKaiNET-transformers
• Edge / MCU users can clearly discover the Minerva path
• A newcomer can copy the current dependency declaration and successfully run a basic getting-started example
• Current getting-started documentation uses consistent version information
• Intentionally older/version-specific documentation is distinguishable from current getting-started documentation
• Tutorials and guides used by the newcomer flow have meaningful page titles rather than Untitled :: SKaiNET
• README and documentation homepage expose essentially the same high-level message and primary CTAs
• There is a defined mechanism or documented process for keeping README and documentation onboarding content aligned
• Primary newcomer-facing links have been verified
• No existing technical/reference documentation is lost as part of the restructuring
• Changes are reviewed and approved by maintainers

---

💬 Additional Notes

The intention of this proposal is not to reduce SKaiNET's technical depth or remove information about formats, compilation, quantization, backends, or deployment targets.

The goal is to improve progressive disclosure:

What is SKaiNET? → What can I do with it? → Start here → Learn the technical details

The underlying documentation structure and technical material are already strong. The main opportunity is improving the first few minutes of the developer journey and ensuring that GitHub and the documentation site present SKaiNET consistently.

This issue can act as the umbrella DARC proposal. If implementation becomes too large for one PR, individual tasks such as version synchronization, page-title cleanup, and shared README/docs content can be split into focused follow-up issues while remaining linked to this proposal.