@@ Line 1,187: / Line 1,187: @@
 This model shall be treated as the implementation source of truth unless superseded by a later approved specification.
+== Dynamic Hub Pages and Navigation ==
+=== Purpose ===
+Areas, Projects, and Topics shall function as navigational hubs in addition to storing user-authored content.
+The system-generated relationship information shall be derived from structured metadata and shall not require the user to manually maintain lists of related pages.
+The implementation should use one generalized '''Hub Page''' subsystem rather than separate unrelated implementations for Areas, Projects, and Topics.
+=== Hub Page Types ===
+The Hub Page subsystem shall apply to:
+* pages whose <code>PageType=Area</code>
+* pages whose <code>PageType=Project</code>
+* pages in the <code>Topic:</code> namespace
+The relationship used to populate the dynamic page list depends on the hub type:
+{| class="wikitable"
+! Hub type !! Relationship query
+|-
+| Area || Pages whose <code>RelatedAreas</code> contains the current Area
+|-
+| Project || Pages whose <code>RelatedProjects</code> contains the current Project
+|-
+| Topic || Pages whose <code>RelatedTopics</code> contains the current Topic
+|}
+=== Hub Page Layout ===
+The rendered page should conceptually contain:
+<pre>
+Page title
+Editable introductory content
+System-generated hub section
+Optional editable additional content
+</pre>
+The generated section shall not be directly editable and shall not be saved as ordinary wikitext.
+Preferred long-term architecture:
+<pre>
+main revision-backed content slot
+system-generated hub component
+secondary revision-backed content slot (optional lower content)
+</pre>
+Before implementing a secondary slot, verify compatibility with the installed MediaWiki version and VisualEditor. If this materially increases version 1 complexity, version 1 may append the generated hub after the main editable content and defer lower editable content.
+=== Area Hub Pages ===
+An Area page shall automatically display:
+* its Parent Area, when one exists
+* its immediate child Areas
+* pages directly associated with the Area
+* sorting controls
+Child Areas are derived from:
+<pre>
+ParentArea = current Area
+</pre>
+Directly associated pages are derived from:
+<pre>
+RelatedAreas HOLDS current Area
+</pre>
+Direct relationships shall be the default. Descendant content may optionally be included through a control such as "Include pages from sub-areas". Descendant inclusion shall be computed from the hierarchy; ancestor Areas shall not be redundantly written into RelatedAreas.
+=== Project Hub Pages ===
+A Project page shall automatically display:
+* Project metadata
+* Related Areas
+* pages whose <code>RelatedProjects</code> contains the current Project
+* sorting controls
+Project-specific metadata such as target date, completion date, progress, or outcome may be displayed when implemented.
+=== Topic Hub Pages ===
+A Topic page shall automatically display:
+* user-authored Topic description
+* pages whose <code>RelatedTopics</code> contains the current Topic
+* sorting controls
+* optional derived counts grouped by PageType
+The counts and lists shall be dynamically derived and not manually maintained.
+=== Hub List Sorting ===
+Every generated relationship list shall support:
+* Page Name
+* Creation Date
+* Last Edit Date
+The query layer shall support ascending and descending order.
+Recommended user-facing choices:
+<pre>
+Name A-Z
+Name Z-A
+Newest Created
+Oldest Created
+Recently Updated
+Least Recently Updated
+</pre>
+Default: <code>Name A-Z</code>, unless configured otherwise.
+=== Hub List Filtering ===
+The architecture shall support future filters including:
+* PageStatus
+* PageType
+* direct relationships versus descendant Area relationships
+Archived content should be excluded from normal hub lists by default where appropriate and exposed through an explicit filter.
+=== Page Creation and Last-Edit Dates ===
+MediaWiki revision history shall remain authoritative for creation and last-edit timestamps.
+For efficient querying and sorting, the application may maintain indexed/cached values:
+<pre>
+CreatedAt
+UpdatedAt
+</pre>
+The implementation shall document how they are populated and refreshed and should avoid querying the earliest revision of every result during ordinary rendering.
+=== Permissions ===
+All generated Hub content shall respect MediaWiki read permissions and future sharing/ACL rules.
+A viewer shall not learn the title, existence, metadata, or count contribution of a page they cannot view.
+This applies to relationship lists, child Areas, counts, filters, autocomplete, Topic breakdowns, Main Page lists, and APIs.
+=== Pagination and Performance ===
+Generated lists shall support pagination and server-side sorting for large result sets.
+The implementation should use indexed query fields, avoid full-table scans, use MediaWiki caching where appropriate, and invalidate/refresh cached output when relevant relationships or metadata change.
+The subsystem should remain practical for hubs containing thousands of related pages.
+=== Empty States ===
+Hub pages shall render useful empty-state messages, such as:
+<pre>
+No pages are currently associated with this Area.
+No pages are currently assigned to this Project.
+No pages currently use this Topic.
+</pre>
+== Main Page Dashboard ==
+In PARA Wiki mode, the Main Page shall provide generated navigation in addition to user-configurable introductory content.
+At minimum it shall display:
+* a hierarchical list of active Areas
+* Active Projects
+=== Area Hierarchy ===
+Top-level Areas are:
+<pre>
+PageType = Area
+PageStatus = Active
+ParentArea = NULL
+</pre>
+Each top-level Area shall display active child Areas recursively or to a configurable display depth.
+The hierarchy shall be derived from <code>ParentArea</code>, never manually maintained.
+Archived Areas shall be excluded by default.
+=== Active Projects ===
+The Main Page shall display:
+<pre>
+PageType = Project
+PageStatus = Active
+</pre>
+Each title shall link to its Project hub page.
+Provide a link to an All Projects view that can include Inception and Archived Projects.
+The initial Main Page should remain concise; recently edited pages, unclassified counts, and Wiki Health summaries may be added later.
+== System Index Pages ==
+The extension shall provide generated index views for:
+* All Areas
+* All Projects
+* All Topics
+* Wiki Health
+* Unclassified Pages
+Where practical these should be MediaWiki Special pages rather than editable normal pages.
+Recommended routes:
+<pre>
+Special:Areas
+Special:Projects
+Special:Topics
+Special:WikiHealth
+Special:UnclassifiedPages
+</pre>
+=== All Areas ===
+Support hierarchical display, Active/Archived filtering, links to Area hubs, and optional direct/descendant page counts.
+=== All Projects ===
+Support PageStatus filtering, Area filtering, sorting by Page Name/Creation Date/Last Edit Date, and links to Project hubs.
+=== All Topics ===
+At minimum show Topic name, link, Active/Archived filtering, and count of accessible pages using the Topic.
+Recommended sorting:
+<pre>
+Name
+Number of Pages
+Recently Used
+Creation Date
+Last Edit Date
+</pre>
+Potential future maintenance views include unused Topics, Topics without descriptions, archived Topics, and possible duplicates.
+== Hub Subsystem Technical Architecture ==
+Implement a generalized service rather than independent Cargo queries embedded in templates.
+Recommended conceptual components:
+{| class="wikitable"
+! Component !! Responsibility
+|-
+| <code>HubService</code> || Determine whether the current page is a Hub and assemble its view model.
+|-
+| <code>HubQueryService</code> || Retrieve related pages using the appropriate relationship.
+|-
+| <code>HubRenderer</code> || Render generated Hub sections.
+|-
+| <code>AreaHierarchyService</code> || Resolve parents, children, descendants, and cycle-safe traversal.
+|-
+| <code>HubSort</code> || Validate and translate supported sort modes.
+|-
+| <code>HubFilter</code> || Validate and apply supported filters.
+|}
+Templates may assist presentation, but relationship selection, permissions, hierarchy traversal, sorting, and validation shall reside in extension code.
+Relationship mapping:
+<pre>
+Area    -> RelatedAreas
+Project -> RelatedProjects
+Topic   -> RelatedTopics
+</pre>
+Adding a future Hub-capable object should not require rewriting the subsystem.
+== Additional API Requirements for Hubs and Indexes ==
+The API shall additionally support operations equivalent to:
+<pre>
+Get hub metadata
+List pages related to an Area
+List pages related to a Project
+List pages related to a Topic
+List child Areas
+List Area descendants
+List Area hierarchy
+List Projects by status
+List Topics
+</pre>
+List operations shall support pagination and, where relevant:
+<pre>
+sort
+direction
+status
+pageType
+includeArchived
+includeDescendants
+limit
+continuation
+</pre>
+Exact names shall follow MediaWiki/API conventions.
+== Additional Acceptance Criteria for Dynamic Hubs ==
+=== Scenario K: Area Hub ===
+Given Personal as an Active Area and several pages with <code>RelatedAreas=Personal</code>:
+* Personal automatically lists those pages.
+* no manually maintained list is required
+* changing RelatedAreas updates Hub membership
+* generated list is not editable as ordinary page text
+=== Scenario L: Hub Sorting ===
+Given related pages with different names, creation dates, and edit dates:
+* sort alphabetically
+* sort by creation date
+* sort by last edit date
+* sorting does not modify metadata
+* sorting works with pagination
+=== Scenario M: Area Hierarchy ===
+Given Photography and Cooking with <code>ParentArea=Hobbies</code>:
+* Hobbies displays them as children
+* each child displays Hobbies as parent
+* hierarchy is generated from ParentArea
+=== Scenario N: Direct Area Relationships ===
+Given <code>Canon EOS R10</code> with <code>RelatedAreas=Photography</code>:
+* it appears in Photography's direct list
+* it does not appear in Hobbies' direct list solely because Photography is beneath Hobbies
+* a descendant-inclusive view may include it
+=== Scenario O: Project Hub ===
+Given <code>Hotels in Rome</code> with <code>RelatedProjects=Plan Italy vacation</code>:
+* Plan Italy vacation automatically lists Hotels in Rome
+* Project Areas are displayed
+* generated list is not directly editable
+=== Scenario P: Topic Hub ===
+Given <code>Topic:Python</code> and multiple pages using it:
+* Topic:Python lists accessible associated pages
+* it may display derived PageType counts
+* archiving the Topic does not destroy relationships
+=== Scenario Q: Main Page Area Tree ===
+* active top-level Areas render hierarchically
+* child Areas appear beneath parents
+* archived Areas are excluded by default
+* links point to Area hubs
+=== Scenario R: Main Page Projects ===
+* Active Projects display by default
+* Inception and Archived Projects do not
+* All Projects view can expose other statuses
+=== Scenario S: Topics Index ===
+* Special:Topics lists accessible Topics
+* Topics can be sorted by name
+* usage counts respect permissions
+* archived Topics can be filtered
+=== Scenario T: Hub Permissions ===
+* inaccessible related pages are not displayed
+* inaccessible titles do not contribute to exposed counts
+* API behavior matches rendered-page behavior
+== Additional Open Design Questions ==
+# Whether version 1 supports editable content both above and below the generated Hub section, or initially only before it.
+# Whether a secondary MediaWiki content slot provides acceptable VisualEditor behavior.
+# Whether descendant-Area inclusion ships in version 1 or is deferred.
+# Whether Hub sort/filter preferences are temporary, per-user, or per-Hub.
+# Exact default pagination size.
+# Whether Topic PageType breakdown counts ship in version 1.
+# Whether Main Page dashboard sections are configurable/reorderable in version 1.
+# Whether system indexes also expose transcludable components in addition to Special pages.

Requirements and Specifications: Difference between revisions