Ocean-Atlas Knowledge Architecture

Ocean-Atlas Knowledge Architecture
- Metadata
1. Purpose
2. Vision
3. Problem Statement
4. Architectural Scope
5. Non-Goals
6. Core Principles
- 6.1 Knowledge First
- 6.2 Single Source of Truth
- 6.3 Stable Identity
- 6.4 Explicit Relationships
- 6.5 Human and Machine Readability
- 6.6 Separation of Knowledge and Presentation
- 6.7 Progressive Structure
- 6.8 Traceability
- 6.9 Version Awareness
- 6.10 Technology Independence
7. Knowledge Model
8. Knowledge Types
- 8.1 Concept
- 8.2 Reference
- 8.3 Guide
- 8.4 Tutorial
- 8.5 Pattern
- 8.6 Example
- 8.7 Architecture
- 8.8 ADR
- 8.9 RFC
- 8.10 Troubleshooting
- 8.11 FAQ
- 8.12 Glossary Entry
- 8.13 Migration Guide
- 8.14 Roadmap Item
9. Knowledge Areas
- 9.1 Getting Started
- 9.2 Core Concepts
- 9.3 DSL Reference
- 9.4 Architecture
- 9.5 Guides
- 9.6 Tutorials
- 9.7 Patterns
- 9.8 Examples
- 9.9 Decisions
- 9.10 Roadmap
- 9.11 FAQ and Troubleshooting
- 9.12 Glossary
10. Organization Principles
- 10.1 Domain Area and Knowledge Type Are Different
- 10.2 Canonical Entry Points
- 10.3 Avoid Mega-Pages
- 10.4 Avoid Organizational Duplication
- 10.5 Folders Are an Implementation Detail
11. Knowledge Identity
- 11.1 Stable IDs
- 11.2 ID Requirements
- 11.3 URL Independence
12. Metadata Architecture
13. Relationship Architecture
- 13.1 Purpose
13. Relationship Architecture
- 13.1 Purpose
- 13.2 Core Relationship Types
- 13.3 Directionality
- 13.4 Relationship Validation
14. Navigation Architecture
- 14.1 Hierarchical Navigation
- 14.2 Topic Navigation
- 14.3 Task Navigation
- 14.4 Role-Based Navigation
- 14.5 Search Navigation
- 14.6 Related-Knowledge Navigation
- 14.7 Contextual Navigation
15. Knowledge Lifecycle
16. Versioning Architecture
- 16.1 Current and Historical Knowledge
- 16.2 Version Applicability
- 16.3 Evolving Specifications
- 16.4 Planned Knowledge
17. Authority and Provenance
18. Ownership and Governance
- 18.1 Ownership
- 18.2 Review
- 18.3 Conflict Resolution
19. Quality Attributes
- 19.1 Correctness
- 19.2 Discoverability
- 19.3 Consistency
- 19.4 Maintainability
- 19.5 Traceability
- 19.6 Reusability
- 19.7 Extensibility
- 19.8 Reliability for AI
20. Search and Retrieval Readiness
- 20.1 Searchable Knowledge
- 20.2 Search Capabilities
- 20.3 Search Ranking Principles
- 20.4 Search Independence
- 20.5 Retrieval Readiness
- 20.6 Retrieval Principles
- 20.7 Technology Independence
21. AI and RAG Readiness
- 21.1 AI as a Consumer
- 21.2 Retrieval Readiness
- 21.3 Chunking Readiness
- 21.4 Source Attribution
- 21.5 Authority Awareness
- 21.6 Version Awareness
- 21.7 Relationship Awareness
- 21.8 Explainability
- 21.9 Technology Independence
- 21.10 Future Evolution
22. Knowledge-Graph Readiness
- 22.1 Graph-Ready Knowledge Model
- 22.2 Logical Versus Physical Representation
- 22.3 Graph Evolution
- 22.4 Architectural Principle
23. Integration Boundaries
- 23.1 Ocean-Lab UI
- 23.2 Compiler and Validation
- 23.3 Ocean Studio and IDEs
- 23.4 Ocean Assistant
24. Content Placement Decision Rules
- Question 1: What is the primary purpose?
- Question 2: What is the primary domain area?
- Question 3: Does canonical knowledge already exist?
- Question 4: Is the content current, proposed, or historical?
- Question 5: Which items does it relate to?
25. Initial Top-Level Structure
- 25.1 Initial Knowledge Taxonomy
26. Example Knowledge Cluster
27. Migration Principles
28. Architectural Constraints
29. Validation Requirements
30. Success Criteria
31. Decisions Established by This Document
32. Deferred Decisions
33. Recommended Next Steps
34. Conclusion

1. Purpose

This document defines the knowledge architecture of Ocean-Atlas, the canonical knowledge platform for the Ocean ecosystem.

It establishes:

what Ocean-Atlas is responsible for;
which kinds of knowledge belong in Ocean-Atlas;
how that knowledge is classified and organized;
how users and systems navigate it;
how knowledge items relate to one another;
how the architecture supports future search, APIs, semantic retrieval, RAG, and AI assistants;
which concerns are intentionally deferred to later implementation and standards work.

This document defines the structural foundation of Ocean-Atlas. All future decisions regarding content organization, documentation standards, website navigation, APIs, search, migration, and AI integration should conform to this architecture.

2. Vision

Ocean-Atlas is the canonical knowledge platform for the Ocean ecosystem, providing structured, searchable, reusable, and traceable knowledge for both humans and software systems.

Ocean-Atlas is not merely a documentation website.

It is the authoritative platform through which Ocean knowledge is:

created;
organized;
reviewed;
published;
discovered;
referenced;
consumed by tools;
retrieved by AI systems;
maintained throughout its lifecycle.

The documentation website is one presentation layer of Ocean-Atlas. Future consumers may include:

Ocean-Lab UI;
Ocean Studio;
Ocean CLI;
Ocean Compiler;
Ocean generators;
IDE extensions;
Ocean Assistant;
automated validation tools;
external integrations.

3. Problem Statement

Ocean knowledge may otherwise become distributed across:

source-code repositories;
Markdown files;
issue trackers;
pull requests;
architecture documents;
ADRs and RFCs;
examples;
comments;
personal notes;
chat discussions;
generated documentation.

This creates several risks:

duplicated or contradictory information;
undocumented architectural decisions;
unclear ownership;
outdated examples;
broken links;
poor discoverability;
tight coupling between documentation and implementation repositories;
insufficient structure for programmatic access;
unreliable AI-generated answers;
loss of important design context over time.

Ocean-Atlas addresses these risks by providing one governed and structured knowledge platform.

4. Architectural Scope

Ocean-Atlas is responsible for knowledge about the Ocean ecosystem, including:

product and platform concepts;
DSL specifications;
supported capabilities;
architecture;
development and usage guides;
tutorials;
design patterns;
examples;
architectural decisions;
proposals;
troubleshooting;
glossary and terminology;
roadmap information suitable for public documentation;
compatibility and version information;
migration guidance;
error and diagnostic explanations.

Ocean-Atlas may store knowledge directly or reference an authoritative external artifact when duplication would create multiple sources of truth.

5. Non-Goals

The initial Ocean-Atlas knowledge architecture does not define or implement:

the website technology stack;
the search engine;
a vector database;
an embedding model;
an LLM provider;
an AI assistant;
a graph database;
a complete knowledge ontology;
detailed Markdown formatting rules;
detailed metadata field syntax;
CI/CD implementation;
authorization implementation;
application source code;
operational monitoring;
source-code API documentation generated from code.

These concerns may be addressed in later stories.

This document must nevertheless ensure that future implementation of those capabilities does not require a fundamental reorganization of existing knowledge.

6. Core Principles

6.1 Knowledge First

Knowledge is the primary asset of Ocean-Atlas.

Website pages, search indexes, API responses, embeddings, and assistant answers are derived representations of the knowledge. Presentation and delivery technologies must not define the knowledge model.

6.2 Single Source of Truth

Each authoritative concept should have one canonical knowledge item.

Other pages may summarize or reference the concept, but they must not create conflicting definitions.

Where knowledge is generated from another authoritative source, Ocean-Atlas must clearly identify that source rather than silently duplicating it.

6.3 Stable Identity

Every independently referenceable knowledge item must have a stable, unique, and permanent identifier.

References must use stable identifiers rather than file paths wherever practical.

File names, folder structures, URLs, and page titles may change. The identity of a knowledge item must remain stable.

6.4 Explicit Relationships

Relationships between knowledge items must be explicit and machine-readable where practical.

Examples include:

a guide uses a DSL element;
an ADR supersedes another ADR;
a pattern applies to a concept;
an example demonstrates an API style;
a troubleshooting page relates to a compiler error;
a migration guide applies between two versions.

This enables navigation today and knowledge-graph capabilities later.

6.5 Human and Machine Readability

Knowledge must be understandable by humans and consistently consumable by software systems.

The architecture must support:

website rendering;
full-text search;
structured filtering;
APIs;
semantic retrieval;
source attribution;
automated validation;
AI-assisted answering.

6.6 Separation of Knowledge and Presentation

Knowledge content must not depend on a particular website framework.

The same knowledge should be reusable through:

a website;
an API;
a CLI;
an IDE;
contextual help;
search;
RAG;
future delivery channels.

6.7 Progressive Structure

Ocean-Atlas should begin with simple, explicit structures:

documents;
stable IDs;
metadata;
typed relationships.

It may evolve later into a formal knowledge graph without requiring existing content to be rewritten.

6.8 Traceability

Important statements, specifications, and decisions should be traceable to their origin, version, owner, or governing decision where applicable.

Users should be able to determine:

whether knowledge is authoritative;
whether it is current;
which version it applies to;
what decision introduced it;
whether it has been deprecated or superseded.

6.9 Version Awareness

Ocean knowledge changes over time.

Ocean-Atlas must distinguish between:

current behavior;
historical behavior;
planned behavior;
deprecated behavior;
version-specific behavior.

Content must not mix these states ambiguously.

6.10 Technology Independence

The knowledge architecture must remain independent from:

the documentation framework;
the programming language;
the database;
the search technology;
the deployment environment;
the AI provider.

Technology choices may implement the architecture but must not redefine it.

7. Knowledge Model

Ocean-Atlas organizes knowledge using four complementary dimensions:

Domain area — what the knowledge is about;
Knowledge type — what kind of knowledge it is;
Lifecycle state — whether it is proposed, current, deprecated, or historical;
Relationships — how it connects to other knowledge.

A page’s folder location alone is not sufficient to define its meaning.

8. Knowledge Types

Ocean-Atlas distinguishes the following primary knowledge types.

8.1 Concept

Explains what something is, why it exists, and how it fits into the Ocean ecosystem.

Examples:

Ocean DSL;
Construct, Reuse, and Augment;
service;
component;
package;
integration;
execution engine.

Concept pages prioritize understanding over exhaustive syntax.

8.2 Reference

Provides precise, authoritative, and complete technical information.

Examples:

@api syntax;
@service properties;
supported API styles;
datatype definitions;
validation rules;
default values;
compiler options.

Reference content should be unambiguous and optimized for lookup.

8.3 Guide

Explains how to accomplish a practical task.

Examples:

creating a REST API;
adding a broker to a bundle;
defining a reusable package;
deploying a generated service;
integrating an external system.

A guide is task-oriented and assumes a specific user goal.

8.4 Tutorial

Provides a learning-oriented sequence that teaches concepts through a complete example.

Examples:

building a first Ocean service;
creating and exporting a package;
constructing a service with API, persistence, and deployment;
creating an integration flow.

A tutorial prioritizes learning progression rather than serving as a concise operational reference.

8.5 Pattern

Documents a reusable solution to a recurring design or implementation problem.

A pattern should explain:

the problem;
the context;
the proposed solution;
trade-offs;
consequences;
applicable Ocean features;
related examples.

8.6 Example

Provides a concrete, executable or illustrative use of Ocean.

Examples may demonstrate:

one DSL feature;
a complete service;
an integration;
a package;
a deployment;
an architectural pattern.

Examples should identify which concepts and references they demonstrate.

8.7 Architecture

Describes the structure, responsibilities, boundaries, interactions, and rationale of Ocean components or subsystems.

Examples:

Ocean compiler architecture;
generation pipeline;
runtime architecture;
Ocean-Atlas architecture;
package resolution model;
deployment architecture.

8.8 ADR

Records an accepted architectural decision.

An ADR captures:

context;
decision;
alternatives;
consequences;
status;
relationships to superseded or superseding decisions.

An ADR describes a decision that has been made.

8.9 RFC

Proposes and discusses a significant change before it becomes an accepted decision.

An RFC may evolve through states such as:

draft;
under review;
accepted;
rejected;
withdrawn;
implemented.

Once an RFC produces an architectural decision, the relationship between the RFC and the resulting ADR or specification must be recorded.

8.10 Troubleshooting

Helps users identify and resolve a known problem.

Examples:

compiler errors;
invalid references;
generation failures;
deployment problems;
configuration mistakes;
version incompatibilities.

Troubleshooting content should connect symptoms, causes, diagnostics, and solutions.

8.11 FAQ

Answers frequently asked questions that do not justify a complete concept, guide, or troubleshooting item.

FAQ entries should link to authoritative knowledge rather than reproduce large sections of it.

8.12 Glossary Entry

Defines an Ocean-specific term or an external term with a specific meaning in Ocean.

A glossary entry should be concise and link to the canonical concept or reference page.

8.13 Migration Guide

Explains how users move between versions, models, features, or architectural approaches.

Examples:

migrating deprecated DSL syntax;
updating package formats;
moving from one API style model to another;
adopting a new generated structure.

8.14 Roadmap Item

Describes an intended direction or planned capability.

Roadmap content must be clearly marked as non-authoritative regarding currently available behavior.

Planned behavior must never be presented as implemented behavior.

9. Knowledge Areas

The top-level knowledge areas define the main navigation and organizational structure of Ocean-Atlas.

9.1 Getting Started

Purpose: Help new users understand Ocean and achieve an initial successful result.

Typical content:

introduction;
prerequisites;
installation;
first project;
quick start;
basic workflow;
next steps.

This section should minimize required prior knowledge.

9.2 Core Concepts

Purpose: Explain the foundational ideas and mental models of Ocean.

Typical content:

Ocean vision and philosophy;
technology independence;
DSL principles;
Construct, Reuse, and Augment;
projects, bundles, and workspaces;
services and components;
generation model;
extension model;
lifecycle concepts.

This section explains what Ocean is and how to think about it.

9.3 DSL Reference

Purpose: Provide authoritative specifications for the Ocean DSL.

Typical structure:

language fundamentals;
common syntax;
primitive and container types;
one section per DSL area;
annotations and modifiers;
validation rules;
cross-section references;
compatibility and version information.

Examples of DSL areas include:

@datatype;
@api;
@config;
@database;
@broker;
@component;
@service;
@expression;
@deploy;
@dashboard;
@artifact;
@package;
@integration;
future DSL sections.

Each DSL section should have one canonical reference entry point.

9.4 Architecture

Purpose: Describe the design and internal structure of the Ocean ecosystem.

Typical content:

ecosystem overview;
compiler;
parser and AST;
registry and validation;
code generation;
runtime;
engine model;
extension architecture;
Ocean-Lab UI;
Ocean-Atlas;
deployment architecture;
security architecture;
integration architecture.

Architecture documentation should distinguish between conceptual architecture and implementation-specific architecture.

9.5 Guides

Purpose: Help users perform specific tasks successfully.

Guides may be organized by task, role, or capability.

Examples:

design an API;
create a service;
configure persistence;
use a message broker;
create a package;
define an integration;
add a generator;
deploy generated artifacts;
troubleshoot validation.

9.6 Tutorials

Purpose: Teach Ocean through guided, end-to-end learning experiences.

Tutorials should progress from simple to advanced and identify prerequisites.

Possible learning paths include:

beginner;
service development;
platform extension;
package authoring;
integration development;
generator development;
architecture and advanced usage.

9.7 Patterns

Purpose: Document recommended and reusable approaches.

Possible categories include:

service design;
API design;
integration;
messaging;
persistence;
package composition;
deployment;
configuration;
security;
extensibility.

Patterns are recommendations, not language specifications.

9.8 Examples

Purpose: Provide concrete implementations that demonstrate Ocean capabilities.

Examples may be classified by:

complexity;
DSL feature;
business domain;
architecture style;
target technology;
completeness;
Ocean version.

Examples should be linked from the concepts, references, guides, and patterns they demonstrate.

9.9 Decisions

Purpose: Preserve important design context and decisions.

This area contains:

ADRs;
accepted RFCs;
rejected RFCs when historically valuable;
superseded decisions;
decision indexes.

Decision records must not replace current reference documentation. Current specifications should describe the present state, while decisions explain why that state exists.

9.10 Roadmap

Purpose: Communicate planned directions and major future capabilities.

Roadmap content should clearly distinguish:

exploratory ideas;
planned initiatives;
committed work;
completed work;
abandoned directions.

Roadmap content is not part of the authoritative current specification.

9.11 FAQ and Troubleshooting

Purpose: Provide quick resolution for common questions and known problems.

This area may provide user-friendly navigation, while individual FAQ and troubleshooting items retain their own stable identities and relationships.

9.12 Glossary

Purpose: Provide consistent definitions for Ocean terminology.

The glossary should prevent ambiguity and terminology drift across documentation.

10. Organization Principles

10.1 Domain Area and Knowledge Type Are Different

A document belongs to a domain area and has a knowledge type.

For example:

@package may have a concept page in Core Concepts;
its full syntax belongs in DSL Reference;
“Create a reusable package” belongs in Guides;
a package-composition solution belongs in Patterns;
a working package belongs in Examples;
the rationale for package dependency rules belongs in an ADR.

These are related knowledge items, not duplicate pages.

10.2 Canonical Entry Points

Every major concept must have a canonical entry point.

The canonical entry point should direct users to:

conceptual explanation;
reference material;
guides;
examples;
patterns;
decisions;
troubleshooting.

This creates a navigable knowledge cluster around each important Ocean concept.

10.3 Avoid Mega-Pages

A page should represent one coherent knowledge unit.

Large pages should be divided when they contain independently referenceable topics.

However, fragmentation should not create pages that are too small to be useful independently.

The preferred unit is:

one page, one primary purpose, one stable identity.

10.4 Avoid Organizational Duplication

The same authoritative content should not be copied into multiple sections.

Instead:

summarize when necessary;
link to the canonical item;
reuse generated fragments only when governance ensures a single source;
clearly identify derived content.

10.5 Folders Are an Implementation Detail

Folder structure may support maintainability and website generation, but it must not be treated as the permanent identity model.

Knowledge items should be referenced through stable IDs and resolved independently from physical file location.

11. Knowledge Identity

11.1 Stable IDs

Every independently referenceable knowledge item must have a stable ID.

Example ID families:

concept.service
concept.package
dsl.api
dsl.package
architecture.compiler
architecture.generation-pipeline
guide.create-service
tutorial.first-ocean-project
pattern.primary-shared-resource
example.todo-rest-api
adr.0019-data-service-database-owner
rfc.integration-model
troubleshooting.compiler.unknown-type
glossary.bounded-context

The exact syntax and validation rules will be finalized in the documentation standards.

11.2 ID Requirements

A knowledge ID must be:

unique;
stable;
meaningful;
independent of file location;
independent of page title;
suitable for machine references;
preserved across reorganizations.

An ID must not be reused for a different concept after its original item is removed.

11.3 URL Independence

Public URLs may be derived from IDs or page slugs, but URLs and IDs are not assumed to be identical.

When a URL changes, the platform should preserve access through redirection where practical.

12. Metadata Architecture

Every knowledge item must include enough structured metadata to support organization, governance, navigation, search, APIs, automated validation, and future AI retrieval.

At the architecture level, the metadata model must support the following concepts:

stable ID;
title;
knowledge type;
domain area;
summary;
lifecycle status;
authority level;
applicable Ocean version or version range;
applicability scope, where relevant;
intended audience, where relevant;
tags;
aliases or former names;
owners or maintainers;
related knowledge;
creation and modification information;
review information;
deprecation information;
supersession information;
source or provenance;
content origin, such as manually maintained, generated, imported, or derived;
canonicality, identifying whether the item is authoritative, summarized, or derived;
language or locale;
visibility or access classification, where applicable.

Applicability scope may identify the specific Ocean component, DSL style, engine, generator, target technology, deployment environment, or other context to which the knowledge applies.

Not every metadata concept must be required for every knowledge type. Requirements should be defined according to the purpose and lifecycle of each knowledge type.

Metadata values that can be obtained reliably from the repository or publishing process, such as commit timestamps or contributors, should not necessarily be duplicated manually.

The detailed schema, required fields, allowed values, defaults, inheritance rules, and serialization format belong to the documentation standards story.

Metadata must use controlled fields and vocabularies where consistency is important. It must not become an uncontrolled collection of arbitrary properties. New metadata should be introduced only when it has a clear platform-level purpose and an identified consumer.

13. Relationship Architecture

13.1 Purpose

Relationships make Ocean-Atlas more than a collection of documents.

They support:

contextual navigation;
related-content discovery;
dependency analysis;
traceability;
impact analysis;
semantic retrieval;
future knowledge-graph construction.

13. Relationship Architecture

13.1 Purpose

Relationships make Ocean-Atlas more than a collection of independent knowledge items.

They provide the semantic connections that enable:

contextual navigation;
related-content discovery;
dependency analysis;
traceability;
impact analysis;
automated validation;
semantic retrieval;
future knowledge-graph construction.

Relationships represent the meaning between knowledge items, not merely hyperlinks between documents. A relationship should express why two knowledge items are connected, allowing both humans and software systems to understand and navigate the Ocean knowledge base consistently.

13.2 Core Relationship Types

Ocean-Atlas should support a controlled vocabulary of relationship types.

Relationships must be explicit, typed, and semantically meaningful. New relationship types should only be introduced when they have a clear architectural purpose.

Structural Relationships

Describe how knowledge is organized.

contains
contained-by
parent-of
child-of

Semantic Relationships

Describe conceptual relationships between knowledge items.

explains
references
demonstrates
example-of
applies-to
requires
related-to

Evolution Relationships

Describe how knowledge evolves over time.

supersedes
superseded-by
replaces
deprecated-by
derived-from

Decision Relationships

Describe relationships between decisions, proposals, and resulting knowledge.

proposed-by
decided-by
implements-decision
affected-by

Technical Relationships

Describe technical or implementation-oriented dependencies.

uses
depends-on
implements
extends
generates
configures
integrates-with

Improve knowledge discovery and user navigation without changing the underlying semantics.

see-also
alternative
next
previous

Governance Relationships

Describe ownership and stewardship of knowledge.

owned-by
maintained-by

Each relationship type should have a clearly defined meaning and intended usage. Relationship types should not overlap unnecessarily, and overly generic relationships should be avoided when a more specific relationship better describes the connection.

13.3 Directionality

Relationships should have a clear direction.

For example:

guide.create-package --references--> dsl.package

tutorial.first-service --requires--> guide.installation

example.audit-service-package --example-of--> dsl.package

pattern.primary-shared-resource --applies-to--> concept.broker

service.todo-api --implements--> dsl.api

adr.package-dependency-resolution --supersedes--> adr.package-imports-v1

Where appropriate, Ocean-Atlas may expose inverse relationships automatically without requiring both directions to be authored manually.

13.4 Relationship Validation

Relationships should be validated automatically wherever practical.

Validation should detect:

unknown knowledge IDs;
duplicate relationships where prohibited;
invalid relationship types;
relationships not permitted for a given knowledge type;
references to removed or archived knowledge where inappropriate;
missing reciprocal lifecycle relationships;
circular relationships where prohibited.

Each knowledge type should define which relationship types it is allowed to originate and receive.

The detailed validation rules and allowed relationship matrix belong to the documentation standards.

Ocean-Atlas should support multiple navigation paths because users approach knowledge with different intents.

Users browse through the approved top-level knowledge areas and their child sections.

This is the primary website navigation structure.

Users navigate around a major Ocean concept and discover:

concept;
reference;
guides;
tutorials;
examples;
patterns;
decisions;
troubleshooting.

Users begin with a goal, such as:

create an API;
define a package;
deploy a service;
connect a broker;
troubleshoot generation.

Task navigation should lead primarily to guides and tutorials.

Future navigation may support different audiences, such as:

Ocean user;
DSL author;
platform developer;
generator developer;
architect;
operator;
contributor.

Role-based navigation should be implemented as an additional view over canonical knowledge, not as duplicated documentation.

Users discover knowledge through keyword search and filters.

Search results should use metadata, knowledge type, area, status, and version information.

Each item should expose meaningful related items based on explicit relationships.

Related content should not depend solely on automated textual similarity.

Ocean tools may request knowledge for a specific context.

Examples:

help for @package;
explanation of a compiler error;
examples for a DSL field;
guidance for a selected UI element;
documentation applicable to a particular Ocean version.

Contextual navigation should resolve knowledge through stable IDs and structured metadata.

15. Knowledge Lifecycle

Knowledge items move through an explicit lifecycle.

Possible states include:

draft — work in progress and not authoritative;
review — ready for review;
approved — accepted and authoritative;
deprecated — still available but no longer recommended;
superseded — replaced by another item;
archived — retained for historical reasons;
rejected — not accepted, primarily applicable to RFCs;
withdrawn — removed from consideration before decision.

The exact allowed states may differ by knowledge type.

For example:

an ADR may be proposed, accepted, superseded, or rejected;
a reference page may be draft, approved, deprecated, or archived;
a roadmap item may be exploratory, planned, active, completed, or cancelled.

Status must be explicit and machine-readable.

16. Versioning Architecture

16.1 Current and Historical Knowledge

Ocean-Atlas must make the current behavior easy to find while preserving historically important information.

Current knowledge should be the default user experience.

Historical knowledge must be clearly identified and must not appear as current guidance.

16.2 Version Applicability

A knowledge item may apply to:

all Ocean versions;
one specific version;
a version range;
versions from a particular release onward;
versions before deprecation or removal.

Version applicability should be structured rather than described only in prose.

16.3 Evolving Specifications

When a specification changes significantly, Ocean-Atlas may either:

update the canonical item and preserve version-specific sections;
maintain separate versioned variants;
archive the old item and introduce a replacement.

The chosen approach should minimize duplication while keeping version behavior unambiguous.

16.4 Planned Knowledge

Planned features must be visibly distinct from implemented features.

RFCs and roadmap items may describe future behavior, but current reference pages must not present that behavior as available until implementation is complete.

17. Authority and Provenance

Every knowledge item should make its authority clear.

Possible authority levels include:

normative specification;
approved architecture;
accepted decision;
recommended guidance;
illustrative example;
proposal;
roadmap information;
historical record.

Where knowledge originates outside Ocean-Atlas, provenance should identify the source.

Examples:

generated from compiler definitions;
imported from an existing repository;
derived from an ADR;
maintained manually by the Ocean architecture team.

Ocean-Atlas should avoid silently copying generated or externally governed content.

18. Ownership and Governance

18.1 Ownership

Each significant knowledge area should have an identifiable owner or maintainer.

Ownership is responsible for:

technical correctness;
review;
lifecycle state;
version accuracy;
deprecation;
resolving conflicting information.

Ownership may be assigned to a team rather than an individual.

18.2 Review

Changes to authoritative knowledge should use a review process appropriate to their impact.

Examples:

typo and formatting changes may use lightweight review;
DSL specification changes require domain or language review;
architecture changes require architectural review;
ADR and RFC changes follow their defined decision process.

18.3 Conflict Resolution

When two knowledge items conflict:

determine their authority and lifecycle status;
identify the current governing specification or decision;
correct or deprecate the invalid item;
preserve historical context where valuable;
add explicit relationships between superseded and replacement knowledge.

Contradictory authoritative knowledge must not remain unresolved.

19. Quality Attributes

Ocean-Atlas should optimize for the following qualities.

19.1 Correctness

Knowledge accurately reflects the relevant Ocean version and accepted decisions.

19.2 Discoverability

Users can find knowledge through hierarchy, topics, tasks, search, and relationships.

19.3 Consistency

Terminology, identity, metadata, and relationships follow shared standards.

19.4 Maintainability

Knowledge can evolve without large-scale reorganization or widespread link breakage.

19.5 Traceability

Important knowledge can be traced to its source, decision, owner, and version.

19.6 Reusability

The same canonical knowledge can be consumed through websites, APIs, tools, and AI systems.

19.7 Extensibility

New knowledge types, areas, relationships, and consumers can be introduced without redesigning the foundation.

19.8 Reliability for AI

Retrieved content must include sufficient identity, context, authority, version, and source information to support grounded answers.

20. Search and Retrieval Readiness

Although the implementation of search is outside the scope of this document, the knowledge architecture must support efficient, accurate, and context-aware retrieval of Ocean knowledge.

Search is a primary capability of Ocean-Atlas and should enable both human users and software systems to discover authoritative knowledge quickly and reliably.

20.1 Searchable Knowledge

Every knowledge item should expose sufficient structured information for indexing and retrieval.

At a minimum, searchable information should include:

stable ID;
title;
summary;
body content;
knowledge type;
domain area;
lifecycle status;
authority level;
applicable version or version range;
tags;
relationships;
headings and logical sections;
glossary terms and aliases where applicable.

The search implementation may additionally derive searchable information from structured metadata and document relationships.

20.2 Search Capabilities

Ocean-Atlas should support multiple complementary search capabilities.

Keyword Search

Locate knowledge using exact words or phrases.

Examples:

@package
REST
RabbitMQ

Symbol Search

Locate language constructs, DSL elements, configuration properties, compiler diagnostics, and other named Ocean artifacts.

Examples:

@integration
generateSwagger
ApiConfig

Structured Search

Filter knowledge using structured metadata.

Examples:

knowledge type;
domain area;
lifecycle status;
authority level;
applicable Ocean version;
tags;
owner;
audience.

Relationship-Aware Search

Search should use explicit knowledge relationships to improve discovery.

For example, a search result for @package may also expose:

related concepts;
reference documentation;
guides;
tutorials;
examples;
patterns;
ADRs;
troubleshooting articles.

Version-Aware Search

Search results should respect version applicability.

Users should be able to retrieve:

current knowledge;
historical knowledge;
planned knowledge;
knowledge applicable to a specific Ocean version.

Current authoritative knowledge should be prioritized by default.

Semantic Search

Ocean-Atlas should eventually support semantic retrieval based on meaning rather than exact wording.

Semantic retrieval should complement, not replace, traditional keyword search.

20.3 Search Ranking Principles

Search results should consider multiple factors, including:

authority level;
lifecycle status;
version applicability;
semantic relevance;
keyword relevance;
relationship proximity;
knowledge type.

Authoritative and current knowledge should generally rank higher than:

deprecated knowledge;
historical knowledge;
draft proposals;
illustrative examples.

Examples remain valuable but should not outrank canonical specifications when both satisfy the same query.

20.4 Search Independence

The knowledge architecture must remain independent of any particular search technology.

Whether implemented using traditional full-text indexing, semantic embeddings, graph traversal, or future retrieval techniques, all search capabilities should operate on the same canonical knowledge model.

Search indexes, embeddings, and retrieval databases are derived artifacts and must never become the authoritative source of knowledge.

20.5 Retrieval Readiness

Ocean-Atlas should support reliable retrieval of knowledge by software systems in addition to interactive user search.

Retrieval should support:

stable ID lookup;
metadata-based retrieval;
relationship traversal;
version-aware retrieval;
authority-aware retrieval;
contextual retrieval;
semantic retrieval;
retrieval of canonical knowledge.

Retrieval should produce deterministic and explainable results suitable for APIs, AI systems, development tools, and automated workflows.

20.6 Retrieval Principles

Retrieval should prefer the most authoritative knowledge applicable to the requested context.

When multiple knowledge items match a request, retrieval should prioritize, where appropriate:

current authoritative specifications;
accepted architecture documents;
approved guidance;
examples and tutorials;
historical or deprecated knowledge.

Retrieval should preserve source attribution and expose sufficient metadata for downstream consumers to determine why a particular knowledge item was selected.

20.7 Technology Independence

The knowledge architecture must remain independent of any particular search or retrieval technology.

Whether implemented using:

traditional full-text indexing;
structured metadata indexes;
semantic embeddings;
vector databases;
graph traversal;
hybrid retrieval;
future retrieval technologies,

all search and retrieval capabilities must operate on the same canonical knowledge model.

Indexes, embeddings, vector databases, graph indexes, and retrieval caches are derived artifacts and must never become the authoritative source of Ocean knowledge.

21. AI and RAG Readiness

Ocean-Atlas is designed to become the authoritative knowledge source for future AI-powered capabilities across the Ocean ecosystem.

AI systems are consumers of Ocean-Atlas knowledge, not owners of it.

Ocean-Atlas remains responsible for governing, organizing, versioning, and validating knowledge. AI systems remain responsible for reasoning, conversation, summarization, and answer generation.

21.1 AI as a Consumer

Future AI capabilities may include:

Ocean Assistant;
contextual help within Ocean-Lab;
Ocean Studio assistance;
IDE assistants;
CLI assistance;
compiler explanations;
architecture guidance;
documentation assistants;
future intelligent automation.

All AI capabilities should retrieve knowledge from Ocean-Atlas rather than maintaining separate copies of Ocean knowledge.

21.2 Retrieval Readiness

Ocean-Atlas should support efficient retrieval of authoritative knowledge for AI systems.

AI retrieval should support:

stable ID lookup;
metadata-based retrieval;
relationship-aware retrieval;
version-aware retrieval;
authority-aware retrieval;
lifecycle-aware retrieval;
contextual retrieval;
semantic retrieval.

Retrieved knowledge should preserve sufficient context for downstream reasoning without requiring the AI system to reconstruct document structure.

21.3 Chunking Readiness

Knowledge should be organized into coherent, independently understandable units.

Knowledge items should support predictable chunking while preserving:

semantic meaning;
stable identity;
section boundaries;
metadata;
relationships;
source attribution.

Chunk boundaries should follow logical knowledge boundaries rather than arbitrary character or token limits whenever practical.

21.4 Source Attribution

Every retrieved knowledge fragment should retain enough information to identify its origin.

AI systems should be able to determine:

the canonical knowledge item;
stable ID;
title;
authority level;
lifecycle status;
applicable version;
source location;
related knowledge.

AI-generated answers should reference canonical Ocean-Atlas knowledge whenever possible.

21.5 Authority Awareness

Not all knowledge has equal authority.

AI systems should distinguish between:

normative specifications;
approved architecture;
accepted decisions;
recommended guidance;
illustrative examples;
proposals;
roadmap items;
historical documentation.

Authoritative specifications should generally take precedence over illustrative or historical material when answering factual questions.

21.6 Version Awareness

AI retrieval should respect version applicability.

When knowledge differs across Ocean versions, AI systems should retrieve and prioritize information applicable to the requested version.

When version information is unavailable, AI systems should clearly communicate assumptions rather than presenting uncertain information as authoritative.

21.7 Relationship Awareness

AI systems should be able to traverse explicit knowledge relationships.

For example, retrieval of a DSL specification may also expose:

related concepts;
examples;
tutorials;
design patterns;
architectural decisions;
troubleshooting guidance.

Relationship traversal should improve completeness without replacing authoritative knowledge.

21.8 Explainability

AI-generated answers should be explainable.

Where practical, AI systems should be able to identify:

which knowledge items contributed to an answer;
why those items were selected;
which Ocean version they apply to;
their authority level.

This improves transparency, trust, and maintainability.

21.9 Technology Independence

The architecture intentionally avoids dependence on any particular AI technology.

Ocean-Atlas should remain compatible with:

Retrieval-Augmented Generation (RAG);
vector databases;
embedding models;
local or hosted language models;
graph-enhanced retrieval;
future AI retrieval techniques.

The underlying AI technology may evolve without requiring changes to the canonical knowledge model.

21.10 Future Evolution

The initial implementation of Ocean-Atlas does not require AI-specific infrastructure.

Instead, the knowledge architecture provides the necessary foundation through:

stable knowledge identities;
structured metadata;
explicit relationships;
lifecycle information;
authority levels;
version applicability.

These capabilities enable future AI systems to retrieve governed, traceable, and authoritative knowledge without requiring fundamental changes to the Ocean-Atlas knowledge model.

22. Knowledge-Graph Readiness

Ocean-Atlas is designed so that its knowledge model naturally forms a semantic knowledge graph.

This architectural capability is independent of the physical storage technology.

Ocean-Atlas does not initially require a graph database or graph-processing engine. Instead, graph-readiness is achieved by designing knowledge around explicit identities, metadata, and relationships from the beginning.

22.1 Graph-Ready Knowledge Model

Every knowledge item contributes to a logical knowledge graph through:

stable knowledge IDs;
typed knowledge items;
structured metadata;
explicit typed relationships;
lifecycle information;
version applicability;
provenance information;
authority information.

These elements define the semantics of the knowledge independently of how it is stored or presented.

22.2 Logical Versus Physical Representation

The logical knowledge graph represents the meaning and relationships of Ocean knowledge.

The physical representation may initially consist of:

Markdown documents;
structured metadata;
repository organization;
generated indexes.

Future implementations may additionally maintain:

graph indexes;
graph databases;
semantic indexes;
vector databases;
other retrieval structures.

These physical representations are derived artifacts and must not become the authoritative source of knowledge.

22.3 Graph Evolution

The initial implementation of Ocean-Atlas intentionally favors simplicity.

The architecture enables progressive evolution without requiring existing knowledge to be rewritten.

A future implementation may introduce capabilities such as:

graph traversal;
relationship inference;
dependency visualization;
impact analysis;
semantic navigation;
graph-enhanced retrieval;
AI-assisted reasoning.

These capabilities should operate on the existing canonical knowledge model rather than introducing an alternative representation.

22.4 Architectural Principle

The Ocean-Atlas knowledge model should always remain graph-capable, regardless of implementation technology.

Whether knowledge is stored in Markdown, relational databases, graph databases, object stores, or future storage technologies, the semantic relationships between knowledge items must remain explicit, stable, and technology-independent.

Knowledge relationships are therefore considered part of the architecture itself rather than an implementation detail.

Future implementations may optimize the storage and traversal of these relationships, but they must preserve the identity, meaning, and governance of the canonical knowledge model.

23. Integration Boundaries

23.1 Ocean-Lab UI

Ocean-Lab may consume Ocean-Atlas through links or APIs for:

contextual help;
DSL documentation;
architecture information;
examples;
validation guidance;
troubleshooting.

Ocean-Lab must not duplicate Atlas knowledge in its own codebase unless required for offline or bootstrap scenarios.

23.2 Compiler and Validation

Compiler and validation messages may reference stable Atlas IDs.

Example:

Error: A primary broker has not been defined.

Knowledge ID: troubleshooting.broker.primary-missing

Ocean-Atlas may then provide:

explanation;
applicable rules;
possible solutions;
examples;
related DSL reference.

The compiler remains responsible for detecting errors. Atlas remains responsible for explaining governed knowledge.

23.3 Ocean Studio and IDEs

Development tools may retrieve:

syntax help;
field descriptions;
examples;
related concepts;
validation rules;
migration guidance.

These integrations should use stable IDs or knowledge APIs rather than scrape website HTML.

23.4 Ocean Assistant

Ocean Assistant should be a consumer of Ocean-Atlas, not part of the core knowledge store.

Atlas supplies governed knowledge and retrieval capabilities. The assistant handles conversation, reasoning, and response generation.

24. Content Placement Decision Rules

When adding new knowledge, contributors should determine placement using the following questions.

Question 1: What is the primary purpose?

Explain what or why → Concept
Define exact behavior or syntax → Reference
Explain how to perform a task → Guide
Teach through a sequence → Tutorial
Present a reusable solution → Pattern
Show a concrete implementation → Example
Describe internal structure → Architecture
Record an accepted decision → ADR
Propose a significant change → RFC
Resolve a known problem → Troubleshooting
Explain movement between versions → Migration Guide

Question 2: What is the primary domain area?

Choose the top-level area that best matches the subject.

The knowledge type and domain area should both be recorded.

Question 3: Does canonical knowledge already exist?

If yes:

update it;
reference it;
extend it with a different knowledge type;
do not create a competing definition.

Question 4: Is the content current, proposed, or historical?

Record the correct status and version applicability.

Question 5: Which items does it relate to?

Add explicit relationships using stable IDs.

25. Initial Top-Level Structure

The initial logical structure of Ocean-Atlas is:

Ocean-Atlas
│
├── Getting Started
│   ├── Introduction
│   ├── Installation
│   ├── Quick Start
│   └── First Project
│
├── Core Concepts
│   ├── Ocean Overview
│   ├── DSL Principles
│   ├── Construct, Reuse, and Augment
│   ├── Projects and Workspaces
│   ├── Services and Components
│   ├── Packages
│   └── Generation Model
│
├── DSL Reference
│   ├── Language Fundamentals
│   ├── Datatypes
│   ├── API
│   ├── Config
│   ├── Database
│   ├── Broker
│   ├── Component
│   ├── Service
│   ├── Expression
│   ├── Deploy
│   ├── Dashboard
│   ├── Artifact
│   ├── Package
│   ├── Integration
│   └── Additional DSL Sections
│
├── Architecture
│   ├── Ecosystem Overview
│   ├── Compiler
│   ├── Parser and AST
│   ├── Registry and Validation
│   ├── Generation Pipeline
│   ├── Runtime
│   ├── Engines
│   ├── Extensions
│   ├── Ocean-Lab UI
│   └── Ocean-Atlas
│
├── Guides
│
├── Tutorials
│
├── Patterns
│
├── Examples
│
├── Decisions
│   ├── ADRs
│   └── RFCs
│
├── Migration
│
├── FAQ and Troubleshooting
│
├── Glossary
│
└── Roadmap

This is a logical architecture, not a mandatory physical folder structure.

The structure may expand, but top-level changes should be deliberate because they affect navigation, ownership, and long-term discoverability.

25.1 Initial Knowledge Taxonomy

Ocean-Atlas organizes knowledge into a set of top-level knowledge areas.

These knowledge areas define the primary logical organization of Ocean knowledge and serve as the foundation for navigation, search, governance, and future retrieval capabilities.

They do not prescribe the physical repository layout, website routing, or storage structure.

The initial knowledge taxonomy consists of the following areas.

Ocean-Atlas
│
├── Getting Started
│
├── Core Concepts
│
├── DSL Reference
│
├── Architecture
│
├── Guides
│
├── Tutorials
│
├── Patterns
│
├── Examples
│
├── Decisions
│   ├── ADRs
│   └── RFCs
│
├── Migration
│
├── FAQ and Troubleshooting
│
├── Glossary
│
└── Roadmap

Each knowledge area contains one or more knowledge items of different knowledge types.

For example, the DSL Reference area contains the canonical specifications for Ocean language elements, while Guides contain task-oriented documentation, Examples contain illustrative implementations, and Architecture contains the structural design of the Ocean ecosystem.

The detailed organization within each knowledge area is expected to evolve as Ocean grows.

The physical repository structure, website navigation, URLs, and generated documentation may organize this knowledge differently, provided they preserve the logical organization, stable identities, and relationships defined by this architecture.

The top-level knowledge taxonomy should remain relatively stable over time. New top-level areas should only be introduced when they represent a distinct category of knowledge that cannot reasonably fit within the existing taxonomy.

26. Example Knowledge Cluster

The @package capability may be represented as a cluster of related knowledge:

concept.package
    explains the purpose and mental model

dsl.package
    defines syntax and normative behavior

guide.create-package
    explains how to create a package

tutorial.reusable-audit-service
    teaches package creation through an end-to-end scenario

pattern.package-shared-resource
    describes a reusable solution for shared resources

example.audit-service-package
    provides a concrete implementation

adr.package-dependency-resolution
    records a governing architectural decision

troubleshooting.package.missing-dependency
    explains a common failure

These items are connected through explicit relationships but retain separate purposes and identities.

This model should be applied consistently to other major Ocean capabilities.

27. Migration Principles

Existing Ocean documentation should be migrated according to this architecture.

Migration should:

inventory existing sources;
identify canonical and duplicate knowledge;
classify each item by type and area;
assign stable IDs;
identify lifecycle state and version applicability;
preserve valuable decision history;
consolidate contradictions;
create explicit relationships;
redirect or retire previous locations;
establish Ocean-Atlas as the canonical destination.

Migration must not blindly reproduce the existing folder structure.

28. Architectural Constraints

The following constraints apply to future Ocean-Atlas implementation:

Knowledge identity must not depend exclusively on file paths.
Presentation code must not be the only way to access knowledge.
Stable IDs must be preserved across reorganizations.
Current, proposed, deprecated, and historical knowledge must be distinguishable.
Relationships must be representable in structured form.
Search indexes and embeddings must be derived artifacts, not sources of truth.
AI-generated answers must link back to canonical knowledge.
The website must not become the authoritative data model.
A future graph database must remain optional.
External consumers should use stable interfaces rather than repository internals where practical.

29. Validation Requirements

The future Ocean-Atlas validation process should be able to detect at least:

duplicate IDs;
missing required metadata;
invalid knowledge types;
invalid lifecycle states;
unresolved internal references;
references to unknown IDs;
invalid relationship types;
missing supersession targets;
broken navigation links;
contradictory version declarations;
orphaned knowledge items;
deprecated content presented as current;
roadmap content presented as implemented behavior.

Detailed validation rules belong to the documentation standards and repository implementation stories.

30. Success Criteria

This knowledge architecture is successful when:

contributors can determine where new knowledge belongs;
users can navigate Ocean knowledge by area, topic, and task;
each important concept has a canonical identity;
duplicate authoritative definitions are avoided;
current and historical knowledge are clearly distinguished;
decisions are connected to resulting specifications;
website structure can evolve without invalidating knowledge identity;
search and APIs can use consistent metadata;
RAG systems can retrieve authoritative, version-aware content;
a future knowledge graph can be created from existing IDs and relationships;
Ocean tools can reference Atlas knowledge reliably.

31. Decisions Established by This Document

This architecture establishes the following decisions:

Ocean-Atlas is a knowledge platform, not only a documentation website.
Ocean-Atlas is the canonical knowledge source for the Ocean ecosystem.
Knowledge and presentation are separate architectural concerns.
Every independently referenceable knowledge item has a stable ID.
Knowledge is classified by both domain area and knowledge type.
Relationships between knowledge items are explicit.
Current, planned, deprecated, superseded, and historical knowledge are distinguishable.
Markdown may be used as an initial storage format, but file structure is not the knowledge model.
Ocean-Atlas is designed for both human and machine consumption.
Search indexes, embeddings, and graph indexes are derived representations.
A graph database is not required initially.
The architecture is designed to support future knowledge graph, RAG, and assistant capabilities.
Ocean-Atlas APIs and integrations should use stable identities rather than website-specific paths.
Concepts, references, guides, tutorials, patterns, examples, decisions, and troubleshooting are separate knowledge types with different purposes.
Roadmap and proposal content must not be presented as current implemented behavior.

32. Deferred Decisions

The following decisions are intentionally deferred:

physical repository folder structure;
documentation framework;
front-matter format;
exact metadata schema;
exact ID syntax and naming rules;
full relationship vocabulary;
website navigation implementation;
search engine;
API protocol and versioning;
storage backend;
graph database;
embedding model;
vector database;
LLM provider;
authentication and authorization;
localization;
offline distribution;
generated documentation strategy.

These decisions must conform to the principles and constraints defined in this document.

33. Recommended Next Steps

After approval of this architecture:

define Ocean-Atlas documentation standards;
define the exact metadata schema;
define stable ID conventions;
define the initial controlled relationship vocabulary;
establish page templates for each knowledge type;
create the repository structure;
create the initial knowledge hierarchy;
begin controlled migration of existing Ocean documentation.

34. Conclusion

Ocean-Atlas must be built around knowledge, not pages.

Its foundation consists of:

Canonical Knowledge
        +
Stable Identities
        +
Structured Metadata
        +
Explicit Relationships
        +
Lifecycle and Version Context

From that foundation, Ocean-Atlas can safely support:

Website
   ↓
Search
   ↓
Knowledge APIs
   ↓
Semantic Retrieval
   ↓
Knowledge Graph
   ↓
RAG
   ↓
Ocean Assistant
   ↓
Ocean Studio, CLI, Compiler, and Future Tools

This architecture allows Ocean-Atlas to begin as a maintainable, structured knowledge repository while preserving a clear evolution path toward a complete knowledge platform for humans and intelligent systems.

Ocean-Atlas Knowledge Architecture

1. Purpose

2. Vision

3. Problem Statement

4. Architectural Scope

5. Non-Goals

6. Core Principles

6.1 Knowledge First

6.2 Single Source of Truth

6.3 Stable Identity

6.4 Explicit Relationships

6.5 Human and Machine Readability

6.6 Separation of Knowledge and Presentation

6.7 Progressive Structure

6.8 Traceability

6.9 Version Awareness

6.10 Technology Independence

7. Knowledge Model

8. Knowledge Types

8.1 Concept

8.2 Reference

8.3 Guide

8.4 Tutorial

8.5 Pattern

8.6 Example

8.7 Architecture

8.8 ADR

8.9 RFC

8.10 Troubleshooting

8.11 FAQ

8.12 Glossary Entry

8.13 Migration Guide

8.14 Roadmap Item

9. Knowledge Areas

9.1 Getting Started

9.2 Core Concepts

9.3 DSL Reference

9.4 Architecture

9.5 Guides

9.6 Tutorials

9.7 Patterns

9.8 Examples

9.9 Decisions

9.10 Roadmap

9.11 FAQ and Troubleshooting

9.12 Glossary

10. Organization Principles

10.1 Domain Area and Knowledge Type Are Different

10.2 Canonical Entry Points

10.3 Avoid Mega-Pages

10.4 Avoid Organizational Duplication

10.5 Folders Are an Implementation Detail

11. Knowledge Identity

11.1 Stable IDs

11.2 ID Requirements

11.3 URL Independence

12. Metadata Architecture

13. Relationship Architecture

13.1 Purpose

13. Relationship Architecture

13.1 Purpose

13.2 Core Relationship Types

Structural Relationships

Semantic Relationships

Evolution Relationships

Decision Relationships

Technical Relationships

Navigation Relationships

Governance Relationships

13.3 Directionality

13.4 Relationship Validation

14. Navigation Architecture

14.1 Hierarchical Navigation

14.2 Topic Navigation

14.3 Task Navigation

14.4 Role-Based Navigation

14.5 Search Navigation

14.6 Related-Knowledge Navigation

14.7 Contextual Navigation

15. Knowledge Lifecycle