moved

# Conflicts:
#	specs/2_systems_s/external-software-tools-repos.md

LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 adminprojects
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

PRODUCT-DEV-OS.md

@@ -1,90 +0,0 @@
-# Product Development And Production Methodology
-
-## Overview
-
-This is a template that will be copied when a new product is to be created.  This template is to be used when an AI is involved because this document helps provide executable structure that an AI can understand to create the product and manage its production.  A change to the product would mean changing the executable structure, not the actual code or the product itself, because AI is the production layer and uses the executable structure layer to produce.  This template guides how to create the product, how to produce it, and improve it.  This process is not just for software products, but also for physical products, because increasingly, AI will assume control of physical production of products via automated test and assembly lines.
-
-### Tools:
-
-* If humans need to think through it → Google Docs to allow for shared working  
-* If AI needs to read it to build something → Markdown in a repo
-
-The most valuable stack is:
-
-1. problem framing
-2. system design
-3. data modeling
-4. AI orchestration
-
-### 3-layer system
-
-1. Knowledge layer   → what the system is supposed to do. The truth via highly structured executable knowledge that AI can understand  
-2. Product layer → takes the knowledge layer and executes it:  develop code, develop the product, produce the product  
-3. Data layer → what the system observes, stores, and learns from based on production. The data validates reality, that leads to iterate above to improve
-
-### Structure For Git Repo
-
-- Changes and commits always tracked. 
-- Branch strategy:  main (production), dev (active development), feature branches (experimental). Flow: feature>>dev>>main 
-
-### Structure For Files
-
-- Use consistent headings
-- Keep sections predictable.  If every file has a predictable structure, AI navigation improves dramatically.
-
-### repo/
-
-README.md \ see template 
-CHANGELOG.md
-VERSION.md \ see template
-PROJECTRULES.md \ see template
-
-### docs/
-*The executable structure layer: product intent, product behavior, systems design, build plan*
-agents.md \ how this repo works, what the structure means, rules for editing code. AI should modify docs before modifying code. All new features must update data-model.md. All tests must pass before merge.
-vision/concept validation/strategy/mission/goals/marketing/sales/distribution/goals/target customer/constraints/success metrics/.md \ use the **B2C framework**. 
-requirements/desired outcomes.md
-user-flows/screen states/actions.md
-architecture.md \- infrastructure, platforms, code bases, tech stack, engineering design, environment \ the [long-term tech stack is here](https://docs.google.com/document/d/1BtcV4Lpv4E8vf5jMHcYmzw__U8ZN0ZCx0-1KTo0Z-1U/edit?tab=t.0)
-environments.md - multiple environments that exist - dev, staging, production
-data-model.md \- how the data flows through the product, where it ends up, how it is , structure, relationships, rules governing it, where stored
-api-spec.md \- AI capabilities, focus for this project. 
-build-plan.md \- sequences, tasks, modules, dependencies, components
-decisions.md \ why we did what we did, why we chose A over B, etc.  Architecture Decision Records (ADR). provide context, decision, risks, consequences. Document using the [decision layer and biases layer](https://docs.google.com/document/d/1VjtP-jPn-wOpE8z5QSVOdk-pPxneyuDDM6z_a9OIpYY/edit?tab=t.0)
-system.md \ map of how the knowledge layer connects to the code, how data flows, how AI should reason about the repo
-
-### srv/
-*The production/execution layer for AI to execute on. Code is created in files.  Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any.*
-app/
-models/
-scripts/
-services/
-ui/
-utils/
-routes/
-
-### data/
-*Data that is already a part of the system (ie.: CRM customer data) or which gets produced from the system. repo/ topline and docs/ are strategy, systems and product development are src/, data is all other functions, pulled from **B2C Framework**
-json-db/
-schemas/
-runtime-exports/
-finance/
-marketing/
-sales/
-support/
-
-### tests/
-*Run time feedback*
-acceptance-tests.md
-qa-checklists.md
-dev-tests/
-
-### ops/
-deployment.md
-monitoring.md
-maintenance.md
-backup.md
-security.md
-
-### config/
-.env files, API's, feature flags, for both dev and production

PROJECTRULES.md

@@ -1,7 +0,0 @@
-# Project Rules
-
-1. Never modify production database schemas without migration scripts.
-2. Update documentation when architecture changes.
-3. Follow directory structure strictly.
-4. Do not place business logic in API controllers.
-5. All new features require tests.

PROJECTRULESPROCESSES.md

@@ -0,0 +1,439 @@
+# Laws of Engineering
+
+via https://lawsofsoftwareengineering.com/
+
+Amdahl’s Law — The maximum performance improvement of a system is constrained by the portion that cannot be parallelized.
+
+Beck’s Law — Optimism is an occupational hazard of programming, and feedback is the treatment.
+
+Benford’s Law — In many real-world datasets, lower digits appear more frequently as leading digits.
+
+Betteridge’s Law of Headlines — Any headline that ends in a question mark can usually be answered “no.”
+
+Brooks’s Law — Adding manpower to a late software project makes it later.
+
+Chesterton’s Fence — Do not remove a system or feature until you understand why it exists.
+
+Conway’s Law — System design reflects the communication structure of the organization that built it.
+
+Cunningham’s Law — The best way to get the right answer online is to post the wrong one.
+
+Dijkstra’s Law — Program testing can show the presence of bugs, not their absence.
+
+Eagleson’s Law — Any code you write will eventually be maintained by someone less experienced than you.
+
+Gall’s Law — A working complex system evolves from a working simple system.
+
+Gilb’s Law — Anything you need to quantify can be measured in a way that is superior to not measuring it at all.
+
+Goodhart’s Law — When a measure becomes a target, it ceases to be a good measure.
+
+Greenspun’s Tenth Rule — Any sufficiently complex program contains an ad hoc implementation of Lisp.
+
+Hick’s Law — Decision time increases with the number and complexity of choices.
+
+Hofstadter’s Law — It always takes longer than expected, even when accounting for this.
+
+Hyrum’s Law — All observable behaviors of a system will be depended on by someone.
+
+Ivory Tower Law — Theoretical designs often fail when applied to real-world constraints.
+
+Kernighan’s Law — Debugging is harder than writing code, so overly clever code is risky.
+
+Knuth’s Optimization Principle — Premature optimization is the root of most inefficiency.
+
+KISS Principle — Simplicity should be a key design goal in systems.
+Law of Demeter — Components should only interact with their immediate neighbors.
+
+Leaky Abstractions — All non-trivial abstractions eventually expose underlying complexities.
+
+Lehman’s Laws — Software must continuously evolve or it becomes less useful over time.
+
+Linus’s Law — Given enough reviewers, all bugs become easier to find.
+
+Liskov Substitution Principle — Subtypes must be usable in place of their base types without altering correctness.
+
+Murphy’s Law — Anything that can go wrong will go wrong.
+Occam’s Razor — The simplest explanation or solution is usually best.
+
+Parkinson’s Law — Work expands to fill the available time.
+
+Pareto Principle — A small number of causes often produce the majority of effects.
+
+Peter Principle — People are promoted until they reach their level of incompetence.
+
+Postel’s Law — Be strict in what you send and tolerant in what you accept.
+
+Reed’s Law — The value of a network grows exponentially with the number of possible subgroups.
+
+Schelling Point — People tend to coordinate around obvious focal points without communication.
+
+Second-System Effect — Engineers overcomplicate systems when designing their second attempt.
+
+Shirky Principle — Institutions try to preserve problems to maintain their relevance.
+
+Tesler’s Law — Every application has an irreducible amount of inherent complexity.
+
+The Law of the Instrument — If all you have is a hammer, everything looks like a nail.
+
+The Unix Philosophy — Build simple, modular tools that do one thing well.
+
+Wadler’s Law — Developers disproportionately focus on minor syntax issues over important architecture concerns.
+
+Wirth’s Law — Software slows down more quickly than hardware speeds up.
+
+Zawinski’s Law — Every program attempts to expand until it can read email.
+
+Atwood’s Law — Any application that can be written in JavaScript will eventually be written in JavaScript.
+
+Bell’s Law of Computer Classes — New computer classes emerge as technology advances and costs decrease.
+
+Brandolini’s Law — Refuting misinformation takes significantly more effort than creating it.
+
+Campbell’s Law — Metrics used for decision-making become corrupted and distort processes.
+
+Clarke’s Third Law — Advanced technology is indistinguishable from magic.
+
+Gallagher’s Law — Inefficiencies grow unnoticed until they become critical problems.
+
+Gresham’s Law (applied) — Lower-quality practices tend to drive out higher-quality ones if unchecked.
+
+Hanlon’s Razor — Do not attribute to malice what can be explained by incompetence.
+
+Metcalfe’s Law — The value of a network grows proportionally to the square of its users.
+
+Moore’s Law — The number of transistors on a chip doubles roughly every two years.
+
+Ninety-Ninety Rule — The final 10% of a project takes another 90% of the time.
+
+Sturgeon’s Law — Ninety percent of everything is of low quality.
+
+The Law of Large Numbers (applied) — Outcomes become more predictable as the number of trials increases.
+
+Zipf’s Law — In many systems, a few items are extremely common while most are rare.
+
+# Project Rules
+
+Dump in rules that I come across - could be anything, specific or general.  
+
+1. Human is the architect (what + why), AI is the operator (how + execution)
+2. In planning phase of projects, the goal is to implement solutions that scale, that fit well int he bigger picture, are easy to maintain, and respect good software engineering paradigms.  AI agents are to think like a founder, not a part-time engineer. Model this expression:  Prototype for 1X; Build for 10X; Engineer for 100X.
+3. Break down projects and problems into many different sub-tasks that you can put a box around.  Think components that are connected together once, not overly interconnected systems with functions consolidated into same script files.  THink folders for components and putting them into discrete folders.  Big sytems are daunting, but not if you break them down into discrete components that also means discrete tasks to work on them.  THe bigger the component or task, the more context memory is needed, which creates problems.  Respect and be good to AI agents by keeping context and memory as small as possible. See Architcture Philosophy below.
+4. Components are evoling fast - a better one could come out tomorrow.  Think about developing systems where you can swap out components and pieces with better ones that emerge.
+5. Never mutate data without reviewing plan, understanding impact, vertifying results
+6. Before deleting, backup, then review, then confirm
+7. If working in windows workstation, handle windows + Linux paths for testing
+8. Never modify production database schemas without migration scripts.
+9. Update documentation when architecture changes.
+10. Follow directory structure strictly.
+11. Do not place business logic in API controllers.
+12. All new features require tests.
+13. AI wil work in isolated environments that give them safe, parallel workspaces.  Never work on production environments. 
+14. Feed AI agents currated context that provides the right info without overwhelming them.
+15. Repos might contain contradictory information.  AI agents will flag that and ask before proceeding to get clarification.
+16. Build components cheap so they can be thrown away when a better one comes along.  
+17. Skills:  build using this evolving tempalte: C:\projects\productivity\skill-template
+
+# Dev. Vs Production
+
+All projects worked on and tested in dev VM,  then pushed to producton via Git.  
+
+1. Dev work
+- build features
+- test
+2. Push to GitHub
+- commit
+- push
+3. Deploy to prod
+- git pull
+- restart
+4. Validate
+5. Tag release
+- v1.2.0
+
+Or, create branch, spin up VM and work on it, test, open PR, merge to main.  
+
+# Architecture Philosophy
+
+## Core Philosophy
+
+Project is designed as a modular AI-native platform composed of small, isolated services with clearly defined responsibilities. The system prioritizes simplicity, replaceability, transparency, and operational control over excessive abstraction and orchestration complexity.
+
+The architecture intentionally leans away from heavy containerization (Docker/Kubernetes) unless a specific application materially benefits from it.
+
+The preferred model is:
+
+* Proxmox VM-level isolation
+* App-level isolation via folders, virtual environments, and systemd services
+* API-driven communication between services
+* Git-based deployment and version control
+* Clear schema and contract boundaries
+* Minimal inter-service coupling
+
+## Key Architectural Principles
+
+### 1. Single Responsibility Repositories
+
+Each repo should own one major responsibility only.
+
+Examples:
+
+* paddlenet-front-website
+* paddlenet-pid-ingestion
+* paddlenet-profile-store
+* paddlenet-search
+* paddlenet-match-engine
+* paddlenet-agent-runtime
+* paddlenet-notifications
+* paddlenet-shared-schemas
+
+This enables:
+
+* easier maintenance
+* independent upgrades
+* lower coupling
+* easier AI-assisted development
+* easier future replacement/refactoring
+
+### 2. API Contracts Over Shared Logic
+
+Services communicate through APIs, not through shared internal code or direct database manipulation.
+
+Think:
+
+* controlled interfaces
+* stable contracts
+* modular boundaries
+
+Not:
+
+* tightly interconnected systems
+* shared assumptions
+* direct cross-service file manipulation
+
+Internal API calls usually remain entirely inside the server or VM and do not traverse the public internet.
+
+Examples:
+
+```text
+http://localhost:8001/api/pid/submit
+http://search-service:8002/api/search
+```
+
+### 3. Avoid Shared Runtime Chaos
+
+Without Docker, runtime isolation becomes critically important.
+
+Every application should have:
+
+* its own folder
+* its own virtual environment
+* its own environment variables
+* its own logs
+* its own systemd service
+* its own dependencies
+
+Recommended structure:
+
+```text
+/srv/apps/paddlenet-pid/
+  .venv/
+  .env
+  logs/
+  src/
+```
+
+Never share:
+
+* Python virtual environments
+* Node modules
+* application configs
+* runtime dependencies
+
+between services.
+
+### 4. One systemd Service Per App
+
+Each service should run independently under systemd.
+
+Examples:
+
+```text
+paddlenet-front.service
+paddlenet-pid.service
+paddlenet-search.service
+paddlenet-match.service
+```
+
+Benefits:
+
+* easier restarts
+* cleaner logs
+* better monitoring
+* fault isolation
+* simpler deployments
+
+Typical deployment flow:
+
+```text
+git pull
+systemctl restart paddlenet-pid
+```
+
+This is intentionally simpler than container rebuild workflows.
+
+### 5. Shared Schema Repository
+
+A dedicated schema repo should define canonical object structures.
+
+Example:
+
+```text
+paddlenet-shared-schemas/
+  pid.schema.json
+  profile.schema.json
+  match.schema.json
+```
+
+These schemas become:
+
+* the contract layer
+* the validation layer
+* the interoperability layer
+
+All services should validate against these schemas.
+
+This is especially important for AI-native systems and agent interoperability.
+
+### 6. Folder Structure Strategy
+
+Use a master workspace folder locally:
+
+```text
+PaddleNet/
+```
+
+Containing multiple independent repos:
+
+```text
+PaddleNet/
+  paddlenet-front-website/
+  paddlenet-pid-ingestion/
+  paddlenet-search/
+```
+
+On servers:
+
+```text
+/srv/apps/
+```
+
+Each app remains operationally isolated.
+
+### 7. Reverse Proxy As Public Entry Point
+
+Only the reverse proxy and public frontend should be internet-facing.
+
+Recommended flow:
+
+```text
+Internet
+   ↓
+Caddy / NGINX
+   ↓
+Frontend
+   ↓
+Internal APIs
+   ↓
+Backend services
+```
+
+Backend services should remain private/internal whenever possible.
+
+### 8. Prefer Simplicity Over Premature Orchestration
+
+Avoid introducing:
+
+* Kubernetes
+* service mesh
+* distributed orchestration
+* event buses
+* Kafka
+* excessive microservices
+
+until scale genuinely requires them.
+
+PaddleNet v1 should optimize for:
+
+* development velocity
+* transparency
+* maintainability
+* operational simplicity
+* AI-assisted coding workflows
+
+#### 9. Docker Is Allowed, But Not Default
+
+Docker is not banned.
+
+Use Docker only when it meaningfully reduces complexity or is operationally required.
+
+Examples:
+
+* third-party apps
+* complex dependency isolation
+* vendor-supported deployments
+* multi-runtime conflicts
+
+Default approach:
+
+* native services
+* folders
+* venvs
+* systemd
+* APIs
+
+### 10. Long-Term Goal
+
+Build a modular, AI-native, antifragile platform where:
+
+* services are replaceable
+* schemas are stable
+* APIs are clean
+* infrastructure remains understandable
+* deployment remains simple
+* AI agents can easily reason about the system
+
+
+# AI Processes
+
+0. Prep: Cleans the working tree by analyzing any uncommitted work and doing the right thing with it (stash or commit). Also runs the entire current test suite and fixes any failures it encounters.
+1. Picks a task from bugs first, or if bugs are complete, a feature that I've completed a spec for
+2. Loads up the spec, and then analyzes it
+3. Loads relevant docs, then looks at relevant code
+4. Develops a testing plan (absolutely critical)
+5. Writes extensive tests for this, then runs them, expecting failures
+6. Develops an extensive plan of its own (I NEVER read this, I do not care)
+7. Runs sub-agents as critical reviewers (review agents) based on 6 personas I've detailed in REVIEW_PERSONAS.md: Designer, Architect, Domain Expert, Code Expert, Performance Expert, Human Advocate. Each of these "owns" a portion of the docs, and reviews against their own documentation, including suggesting where their own docs need to be adapted.
+8. Adapts plan based on review agent reviews, and loops to 7 until green light from all review agents
+9. Implements the plan, including documentation adjustments (docs live in the same code base under Docs)
+10. Runs type checking, linting, compiler, other static analysis tools such as bundle size reporter, as many things as possible, and of course the relevant tests themselves, and verifies that it works, iterating as it goes. Be as strict as possible with your type checking and linting system. I used to be anti strictness, but that was when I was a wetware dev. For agents, I want the most strictness possible.
+11. Run the entire test suite to protect against regressions, fix any new issues
+12. Runs the review agents again on the implementation diff, and loops back to step 10 until getting a green light from all review agents.
+13. Add any encountered unrelated TODOs for human review that they've noticed along the way to the TODO doc
+14. Wrap-up: write a CHANGELOG entry, commit with a detailed commit message meant for human context when reviewing the code. (More on commits later)
+15. Loop back to the beginning (step 1), and select the next task or spec.
+16. When completely done, write up a report for human review. Extremely concise. Details live in commit messages.
+
+Only give an AI a few rounds to fix a problem because if not fixed, then repeated rounds offer diminishing returns of fixing, and more rounds cost more tokens without proportional improvements.  Knowing when to stop is important
+
+# Human Processe After AI Processes
+
+1. Review: Check the changelog and agent recap. Then go commit by commit, reviewing each commit message, implementation diff, tests, and docs changes.
+2. Stacked commits: I keep all commits in the same branch so they stack on each other (a good use for stacked PRs, btw). Improvements carry forward to each subsequent commit. Fewer conflicts, better results, less duplicative work.
+3. Quick fixes: If I need to correct something quickly, I do it using an interactive agent session or by hand. But before I do, I ALWAYS analyze and correct the docs, workflow, and validations/testing first.
+4. Postmortem: If the agent misbehaved, don't just fix the code. Don't tell it to fix the code either. Use that valuable context to figure out why it did the wrong thing. Have it analyze its own context and tell you what docs, skills, or workflow led it astray, and what improvements would make it make the right decision next time. Have it fix those issues first — be diligent, because you can amortize the improvement over the rest of your project. Only after that, have it fix the original issue. Use that feedback cycle and continuous improvement to get to a point where it is making the right decisions more often than not.
+5. Manual testing: I check almost every change manually and thoroughly. Not just to catch bugs, but to catch gaps in my docs, skills, specs, validations/tests, and my own understanding of the system. And fix them!
+6. Spec writing: Then I get back to the first part — gathering requirements, writing specs, doing architecture, and thinking a lot.
+
+# Notes
+Automated testing is incredibly important. This WILL NOT WORK if you don't have a super robust end-to-end testing harness in place and excellent docs so the agents can create their own tests.

README.md

@@ -1,29 +1,200 @@
-Create a root README.md that explains the repo.
+# Product Development And Production Methodology
 
-Example:
+## Overview
 
-# Project Name
+This repository is a spec-driven, AI-native product development operating system where structured Markdown (knowledge layer) defines the system, AI agents execute against it to generate and run the product (execution layer), and data feeds back to continuously improve it—making the repository itself an executable blueprint for both digital and physical product creation.
 
-## Purpose
+It represents a new methodology for creating products and services as AI becomes the primary execution and production layer. AI is no longer limited to writing code; it is increasingly capable of conducting research, running tests, generating new materials, prototyping products, and operating automated production systems. As a result, new paradigms are emerging for how we communicate intent to AI. This product development OS is my approach to structuring that communication—translating strategy into executable specifications that AI can reliably interpret and act upon.
-What the system does.
 
-## Architecture Overview
+This repository serves as a reusable template that is copied each time a new product is created. It provides the structured, executable framework required for AI to understand, build, and manage the product and its production lifecycle. As the system evolves, I continuously refine and expand this repository to improve how effectively AI can operate within it.
-High level explanation.
 
-## Repository Structure
+But it is not just for products.  My thoughts are to have a template that is applicable for anything, from starting a business, designing new products, launching them, and creating AI agents and workflows aginst it all. What if I want to design an agent to remove, clean and reassemble a rear hub on my road bike? Use this process. Much of the future will be run by agents doing digital and physical tasks.  This OS is attempting to lay the groundwork for building agents to do things.  
 
-repo/
+In this model, changes to something (company, product, service, workflow, process) are made by updating the executable structure—not manually modifying code or production systems directly. The knowledge layer defines the desired state, and AI acts as the development and production engine that implements those changes.
-  docs/
+
-  src/
+This framework guides the full lifecycle for starting a company and building products: how to define a product, how to build it, how to produce it, and how to continuously improve it through feedback from real-world data. While immediately applicable to software, it is equally designed for physical products, as AI increasingly integrates with automated testing, prototyping, and manufacturing systems.
-  data/
+
-  tests/
+I organize the layers according to the 8 core functional areas of a business that I created, [as defined here](https://eddiesoehnel.com/startup-roadmap/).
-  ops/
+
+### Process Boundaries:
+
+* If humans need to think through it → Google Docs to allow for shared working  
+* If AI needs to read it to build something → Markdown in a repo
+* You want to map strategy >>> structured specs >>> agent execution.  Strategy is business realm (problem you solve, differertiators, moats, growth strategy), which gets turned into structures specs that AI agents use to build the product to satisfy the strategy.
+
+The most valuable stack is:
+
+1. problem framing
+2. system design
+3. data modeling
+4. AI orchestration
+
+### 3-layer system
+
+1. Knowledge layer (specs/)  → what the system is supposed to do and how to do it. The truth via highly structured executable knowledge that AI can understand. Structure leads to intelligence.  Smarter AI models help, but if poorly structured, then failure.  Well structure knowledger layers can succeed even with average models. 
+2. Product layer (tasks/ and srv/) → takes the knowledge layer and executes it:  develop code, develop the product, produce the product.
+3. Data layer (data/) → what the system observes, stores, and learns from based on execution and real-world response (like from customers on product use, feedback, results, outcomes). The data validates reality, that leads to iterate above to improve.
+
+### Intelligence Vs Code
+Intelligence is in specs/.
+
+Execution is in the srv/, and execution is deterministic. Deterministic is code calls, code execution, cron jobs.  It just does, but does not think.  If the task is exact and repetable, use deterministic code.  
+
+If the task requires judgement or interpretation, then it is in specs/ (skill.md files to be exact). It use to be that we had to force everything into code - logic that was fuzzy, required interpretation and still terrible at intelligence.  Now, we can collapse that cognitive logic that was in a lot of code into skills.  LLMs introduce massive intelligence into the process that never existed.  So, now, we have code that executes and scales, but now we can layer on intelligence to do it for us, in place of us humans.  
+
+Instead of trying to encode complex reasoning in deterministic code (if/then logic), we move that reasoning into spec/skills that guide the LLM. We keep all execution, control flow, and precision tasks in code, and only offload judgment and interpretation to the model. 
+
+Code scales execution and guarantees correctness. 
+
+Spec/Skills scale intelligence and adapt automatically as models improve. When the model improves, every skills improves automatically without changing the code. That is how we can get 10x-100x improvement from the same system, with an improved AI model.  
+
+### Modular
+
+Everything is modular, especially agents and code.  We create small modules of everything so that when a better one comes along (either we create it or an open source one comes along), we can swap it out of the system.  
+
+
+### Structure For Git Repo
+
+- Changes and commits always tracked. 
+- Branch strategy:  main (production), dev (active development), feature branches (experimental). Flow: feature>>dev>>main 
+
+### Structure For Files
+
+- Use consistent headings
+- Keep sections predictable.  If every file has a predictable structure, AI navigation improves dramatically.
+
+#### repo/
+
+- README.md \ high level overview of project; but copy out the contents in this file to the overview file to allow an AI to understand the basis for this repo and its structure for product development.  
+- CHANGELOG.md \
+- VERSION.md \ 
+- PROJECTRULESPROCESSES.md \ agent and human rules/processes
+
+##### specs/
+
+*The executable structure layer, organized by main function and in order*
+
+- many docs could be in these folders 
+- decisions.md \ be sure to always have this.  Why we did what we did, why we chose A over B, etc.  Architecture Decision Records (ADR). provide context, decision, risks, consequences. Document using the [decision layer and biases layer](https://docs.google.com/document/d/1VjtP-jPn-wOpE8z5QSVOdk-pPxneyuDDM6z_a9OIpYY/edit?tab=t.0)
+- skills go here. 
+
+
+###### 1_strategy_s
+
+- vision/concept validation/strategy/mission/goals/marketing/sales/distribution/goals/target customer/constraints/success metrics/.md \ use the **B2C framework**.  
+
+###### 2_systems_s
+
+- api-spec.md \- AI capabilities, focus for this project.
+- architecture.md \- infrastructure, platforms, code bases, tech stack, engineering design, environment \ the [long-term tech stack is here](https://docs.google.com/document/d/1BtcV4Lpv4E8vf5jMHcYmzw__U8ZN0ZCx0-1KTo0Z-1U/edit?tab=t.0)
+- data-model.md \- how the data flows through the product, where it ends up, how it is , structure, relationships, rules governing it, where stored
+- environments.md - multiple environments that exist - dev, staging, production
+- system.md \ map of how the knowledge layer connects to the code, how data flows, how AI should reason about the repo
+- config/
+- - .env files, API's, feature flags, for both dev and production
+ 
+###### 3_product_development_s
+
+- user-flows/screen states/actions.md
+- system-ontology-framework: A framework that defines a system ontology approach where a complex software system is modeled as a structured graph (nodes and relationships) that serves as the single source of truth—allowing AI to automatically generate diagrams, detect issues, simulate changes, and even build code. It’s important because it transforms system design from static documentation into a machine-readable, AI-operable model, enabling automation, consistency, and far more intelligent development and scaling of software systems.
+
+###### 4_finance_s
+
+###### 5_production_logistics_s
+
+###### 6_marketing_s
+
+###### 7_sales-distribution_s
+
+###### 8_support_s
+
+ 
+##### tasks-workflows
+
+###### Workflows And Agents 
+
+Let's define these.  
+
+1. Execution Units is something that does work:  py script, cron job, API call, function
+2. Service Layer is a reusable unit that performs a defined function: 
+3. An agent is a system that decides what to do next.  It is the harness that calls a LLM model to help apply judgement and reasoning about what to do next.  
+- It does not have to call an LLM - it could be a rules-based decision tree or a predefined flow. We could call this an automation controler.  
+- And if judgement and reasoning are required, we can call this an LLM controler, because now it calls for an LLM.  
+
+For me, a project (this repo) could encompass many agents, and agents are either automation controlers or LLM controlers, comprised of service layers (which could on their own can call an LLM), built by execution units.  An agent is a workflow, and workflows can be completed by agents or humans or a mix of both. 
+
+Starting from the top, I have projects (this repo as template), workflows in the project, agents in workflows and orchestrators (humans) in workflows.  And workflows can include LLM conmtrolers or automation controlers, comprised of service layers, built by execution units. 
+
+Workflows repeat, and tasks can repeat but would be defined as one-time executions for purposes of this repo.  
+
+How to build Agents.  That is another process I am building and will update here in future. [Closed link for now](https://docs.google.com/document/d/1YH9-8RATyseuqbhBy9qBdhG_pIc88yt3ePokT8eyRkk/edit?tab=t.0)  
+
+*tasks items in separate documents* 
+
+date_build-plan.md \ sequences, tasks, modules, dependencies, components
+
+##### srv/
+
+*The production/execution layer for AI to execute on. Code is created in files.  Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any.*
+
+###### digital 
+
+*digital/software-based products/services*
+
+- app/
+- models/
+- scripts/
+- services/
+- ui/
+- utils/
+- routes/
+
+###### physical
+
+*physical-based products/services*
+
+##### data-ops/
+
+*Data that is already a part of the system (ie.: CRM customer data) or which gets produced from the system. repo/ topline and docs/ are strategy, systems and product development are src/, data is all other functions, pulled from **B2C Framework**
+
+###### 1_strategy_d
+
+
+###### 2_systems_d
+
+- json-db/
+- schemas/
+- runtime-exports/
+- deployment.md \
+- monitoring.md \
+- maintenance.md \
+- backup.md \
+- security.md \
+ 
+###### 3_product_development_d
+
+
+###### 4_finance_d
+
+
+###### 5_production-logistics_d
+
+
+###### 6_marketing_d
+
+
+###### 7_sales-distribution_d
+
+
+###### 8_support_d
+
+
+##### tests/
+
+*Run time feedback*
+- acceptance-tests.md \
+- qa-checklists.md \
+- dev-tests/
 
-## Development Workflow
 
-1. Edit docs
-2. Generate code
-3. Run tests
-4. Deploy
 
-This becomes the entry point for AI tools.

data-ops/1_strategy_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/2_systems_d/json-db/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/2_systems_d/runtime-exports/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/2_systems_d/schemas/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/3_product_development_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/4_finance/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/5_production-logistics_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/6_marketing_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/7_sales-distribution_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

data-ops/8_support_d/.gitkeep.md

@@ -0,0 +1 @@
+keep

docs/agents.md

@@ -1,14 +0,0 @@
-
-# Context
-To understand the general process for this repo, please review the PRODUCT-DEV-OS.md file.  
-
-# This Repo
-
-how this repo works
-what the structure means
-rules for editing code
-
-
-# Additional General Requirements
-
- Code is created in files.  Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any.

docs/architecture.md

@@ -1 +0,0 @@
-environments.md

docs/build-plan.md

@@ -1 +0,0 @@
-api-spec.md

docs/data-model.md

@@ -1 +0,0 @@
-api-spec.md

docs/decisions.md

@@ -1 +0,0 @@
-api-spec.md

docs/environments.md

@@ -1 +0,0 @@
-data-model.md

docs/system.md

@@ -1 +0,0 @@
-api-spec.md

specs/2_systems_s/config/.gitkeep.md

@@ -0,0 +1 @@
+temp file placeholder

specs/2_systems_s/data-model.md

@@ -0,0 +1 @@
+data-model.md

specs/3_product_development_s/system-ontology-framework/app.js

@@ -0,0 +1,286 @@
+console.log('APP.JS LOADED');
+
+const GRAPH_URL = 'lod_graph_cytoscape.json';
+
+function cleanValue(value) {
+  if (value == null) {
+    return null;
+  }
+
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.toLowerCase() === 'nan' || trimmed.toLowerCase() === 'undefined') {
+      return null;
+    }
+    return trimmed;
+  }
+
+  if (typeof value === 'number' && Number.isNaN(value)) {
+    return null;
+  }
+
+  return value;
+}
+
+function normalizeId(value) {
+  const cleaned = cleanValue(value);
+  return cleaned == null ? null : String(cleaned).trim();
+}
+
+function pickNodeId(data, index) {
+  const rawId = normalizeId(data['node-id'])
+    || normalizeId(data.label)
+    || normalizeId(data.name)
+    || normalizeId(data.id);
+
+  if (!rawId || rawId.startsWith('{')) {
+    return 'node-' + (index + 1);
+  }
+
+  return rawId;
+}
+
+function pickLabel(data, fallbackId) {
+  return normalizeId(data.label)
+    || normalizeId(data['node-id'])
+    || normalizeId(data.name)
+    || normalizeId(data['sub-module'])
+    || fallbackId;
+}
+
+function normalizePayload(payload) {
+  if (Array.isArray(payload)) {
+    return payload;
+  }
+
+  if (Array.isArray(payload && payload.elements)) {
+    return payload.elements;
+  }
+
+  const nodes = Array.isArray(payload && payload.nodes) ? payload.nodes : [];
+  const edges = Array.isArray(payload && payload.edges) ? payload.edges : [];
+  return nodes.concat(edges);
+}
+
+function buildGraph(rawItems) {
+  const nodes = [];
+  const edges = [];
+  const nodeIds = new Set();
+
+  rawItems.forEach(function (item, index) {
+    const data = (item && item.data) || item || {};
+    const source = normalizeId(data.source || data.from);
+    const target = normalizeId(data.target || data.to);
+
+    if (source && target) {
+      edges.push({
+        data: {
+          id: normalizeId(data.id) || 'edge-' + (edges.length + 1),
+          source: source,
+          target: target,
+          label: normalizeId(data.label) || '',
+          'edge-type': normalizeId(data['edge-type']) || normalizeId(data.label) || '',
+          entity: normalizeId(data.entity),
+          execution: normalizeId(data.execution),
+          schedule: normalizeId(data.schedule),
+          criticality: normalizeId(data.criticality)
+        }
+      });
+      return;
+    }
+
+    const id = pickNodeId(data, index);
+    if (!id || nodeIds.has(id)) {
+      return;
+    }
+
+    nodeIds.add(id);
+    nodes.push({
+      data: {
+        id: id,
+        label: pickLabel(data, id),
+        type: normalizeId(data.type),
+        module: normalizeId(data.module),
+        submodule: normalizeId(data['sub-module']),
+        codebase: normalizeId(data['code-base']),
+        environment: normalizeId(data['execution-environment'])
+      }
+    });
+  });
+
+  const filteredEdges = edges.filter(function (edge) {
+    return nodeIds.has(edge.data.source) && nodeIds.has(edge.data.target);
+  });
+
+  return { nodes: nodes, edges: filteredEdges };
+}
+
+function setStatus(message, isError) {
+  const cyContainer = document.getElementById('cy');
+  cyContainer.innerHTML = '';
+  cyContainer.style.display = 'grid';
+  cyContainer.style.placeItems = 'center';
+  cyContainer.style.color = isError ? '#9f1239' : '#1f2937';
+  cyContainer.style.font = '600 16px/1.4 system-ui, sans-serif';
+  cyContainer.textContent = message;
+}
+
+function colorForType(type) {
+  const normalized = (type || '').toLowerCase();
+
+  if (normalized === 'ui') {
+    return '#2563eb';
+  }
+
+  if (normalized === 'script') {
+    return '#0f766e';
+  }
+
+  if (normalized === 'datastore') {
+    return '#a16207';
+  }
+
+  return '#475569';
+}
+
+async function loadGraph() {
+  try {
+    const res = await fetch(GRAPH_URL, { cache: 'no-store' });
+    if (!res.ok) {
+      throw new Error('Fetch failed: ' + res.status + ' ' + res.statusText);
+    }
+
+    const rawText = await res.text();
+    const sanitizedText = rawText.replace(/\bNaN\b/g, 'null');
+    const payload = JSON.parse(sanitizedText);
+    const rawItems = normalizePayload(payload);
+    const graph = buildGraph(rawItems);
+
+    console.log('GRAPH COUNTS:', {
+      rawItems: rawItems.length,
+      nodes: graph.nodes.length,
+      edges: graph.edges.length
+    });
+
+    if (!graph.nodes.length) {
+      setStatus('No valid nodes found in lod_graph_cytoscape.json', true);
+      return;
+    }
+
+    document.getElementById('cy').style.display = 'block';
+
+    graph.nodes.forEach(function (node) {
+      node.data.color = colorForType(node.data.type);
+    });
+
+    const cy = cytoscape({
+      container: document.getElementById('cy'),
+      elements: graph.nodes.concat(graph.edges),
+      style: [
+        {
+          selector: 'node',
+          style: {
+            label: 'data(label)',
+            'background-color': 'data(color)',
+            color: '#ffffff',
+            'text-wrap': 'wrap',
+            'text-max-width': 120,
+            'text-valign': 'center',
+            'text-halign': 'center',
+            'font-size': 12,
+            'font-weight': 700,
+            'text-outline-width': 2,
+            'text-outline-color': '#0f172a',
+            'text-outline-opacity': 0.18,
+            width: 72,
+            height: 72,
+            'border-width': 2,
+            'border-color': '#0f172a',
+            'border-opacity': 0.28,
+            'overlay-opacity': 0,
+            'shadow-blur': 18,
+            'shadow-color': '#0f172a',
+            'shadow-opacity': 0.12,
+            'shadow-offset-x': 0,
+            'shadow-offset-y': 6
+          }
+        },
+        {
+          selector: 'node[type = "UI"]',
+          style: {
+            shape: 'round-rectangle'
+          }
+        },
+        {
+          selector: 'node[type = "Datastore"]',
+          style: {
+            shape: 'diamond'
+          }
+        },
+        {
+          selector: 'node[type = "Script"]',
+          style: {
+            shape: 'ellipse'
+          }
+        },
+        {
+          selector: 'edge',
+          style: {
+            width: 3,
+            label: 'data(label)',
+            color: '#334155',
+            'font-size': 10,
+            'font-weight': 600,
+            'text-background-color': '#ffffff',
+            'text-background-opacity': 0.9,
+            'text-background-padding': 3,
+            'text-rotation': 'autorotate',
+            'curve-style': 'bezier',
+            'line-color': '#64748b',
+            'target-arrow-color': '#64748b',
+            'target-arrow-shape': 'triangle',
+            'arrow-scale': 1.1,
+            'overlay-opacity': 0
+          }
+        },
+        {
+          selector: 'edge[edge-type = "writes"]',
+          style: {
+            'line-style': 'dashed'
+          }
+        },
+        {
+          selector: 'edge[edge-type = "returns"]',
+          style: {
+            'line-color': '#7c3aed',
+            'target-arrow-color': '#7c3aed'
+          }
+        },
+        {
+          selector: 'edge[edge-type = "navigates"]',
+          style: {
+            'line-color': '#db2777',
+            'target-arrow-color': '#db2777'
+          }
+        }
+      ],
+      layout: {
+        name: 'breadthfirst',
+        directed: true,
+        spacingFactor: 1.15,
+        padding: 60,
+        fit: true,
+        animate: false
+      }
+    });
+
+    cy.ready(function () {
+      console.log('GRAPH READY:', cy.elements().length);
+    });
+  } catch (error) {
+    console.error('GRAPH LOAD FAILED:', error);
+    setStatus('Graph load failed: ' + error.message, true);
+  }
+}
+
+loadGraph();

specs/3_product_development_s/system-ontology-framework/graph_edges_nodes.json

@@ -0,0 +1,942 @@
+{
+  "nodes": [
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "file:login.js",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "js",
+      "type": "Script",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "file:login.html",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "html",
+      "type": "UI",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "login API",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "py",
+      "type": "Script",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "auth system",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "py",
+      "type": "Script",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "backend/vm",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "environment config",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": ".env",
+      "type": "Datastore",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "infrastructure",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "localStorage ",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "browser DOM (in memory)",
+      "type": "Datastore",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "file:dashboard.html",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "html",
+      "type": "UI",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": "DOM (#msg)",
+      "location": "srv/apps/lod-api/ui/static/",
+      "code-base": "browser DOM (in memory)",
+      "type": "Datastore",
+      "retry-policy": "no",
+      "indempotent": "yes",
+      "logging": "yes",
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": "browser/client",
+      "vm-environment": "lod-dev-app, lod-prod-app",
+      "owner": "system",
+      "external-connections": NaN,
+      "system-version": "1.0.0",
+      "component-version": "1.0.0",
+      "script-version": "1.0.0"
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    },
+    {
+      "module": "customer-db",
+      "sub-module": "login",
+      "active": "prod",
+      "node-id": NaN,
+      "location": NaN,
+      "code-base": NaN,
+      "type": NaN,
+      "retry-policy": NaN,
+      "indempotent": NaN,
+      "logging": NaN,
+      "metrics": NaN,
+      "alerts": NaN,
+      "execution-environment": NaN,
+      "vm-environment": NaN,
+      "owner": NaN,
+      "external-connections": NaN,
+      "system-version": NaN,
+      "component-version": NaN,
+      "script-version": NaN
+    }
+  ],
+  "edges": [
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.html-login.js-calls",
+      "from-node": "login.html",
+      "to-node": "login.js",
+      "edge-type": "calls",
+      "entity": "user",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "submitted",
+      "dependencies": "login.html",
+      "criticality": "high",
+      "execution-environment": "browser/client"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.js-login.js-validates",
+      "from-node": "login.js",
+      "to-node": "login.js",
+      "edge-type": "validates",
+      "entity": "user",
+      "execution": "event",
+      "schedule": "on submit",
+      "state-transition": "validated",
+      "dependencies": "login.html",
+      "criticality": "high",
+      "execution-environment": "browser/client"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.js-login API (/login)   (API)-calls",
+      "from-node": "login.js",
+      "to-node": "login API (/login)   (API)",
+      "edge-type": "calls",
+      "entity": "credentials",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "validated",
+      "dependencies": "login.html",
+      "criticality": "high",
+      "execution-environment": "backend/vm"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login API (/login)   (API)-environment config   (DataStore / External)-reads",
+      "from-node": "login API (/login)   (API)",
+      "to-node": "environment config   (DataStore / External)",
+      "edge-type": "reads",
+      "entity": "credentials",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "validated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "backend/vm"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login API (/login)   (API)-auth system          (Script / Backend logic)-validates",
+      "from-node": "login API (/login)   (API)",
+      "to-node": "auth system          (Script / Backend logic)",
+      "edge-type": "validates",
+      "entity": "credentials",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "authenticated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "infrastructure"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login API (/login)   (API)-login.js-returns",
+      "from-node": "login API (/login)   (API)",
+      "to-node": "login.js",
+      "edge-type": "returns",
+      "entity": "token",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "authenticated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "backend/vm"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.js-localStorage         (DataStore)-writes",
+      "from-node": "login.js",
+      "to-node": "localStorage         (DataStore)",
+      "edge-type": "writes",
+      "entity": "token",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "authenticated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "browser/client"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.js-dashboard.html       (UI)-navigates",
+      "from-node": "login.js",
+      "to-node": "dashboard.html       (UI)",
+      "edge-type": "navigates",
+      "entity": "token, session",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "authenticated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "browser/client"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": "login.js-DOM (#msg)           (UI component, optional)-writes",
+      "from-node": "login.js",
+      "to-node": "DOM (#msg)           (UI component, optional)",
+      "edge-type": "writes",
+      "entity": "error message",
+      "execution": "user",
+      "schedule": "on submit",
+      "state-transition": "authenticated",
+      "dependencies": "login.js",
+      "criticality": "high",
+      "execution-environment": "browser/client"
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    },
+    {
+      "module": "customer-db",
+      "active": "prod",
+      "edge-id": NaN,
+      "from-node": NaN,
+      "to-node": NaN,
+      "edge-type": NaN,
+      "entity": NaN,
+      "execution": NaN,
+      "schedule": NaN,
+      "state-transition": NaN,
+      "dependencies": NaN,
+      "criticality": NaN,
+      "execution-environment": NaN
+    }
+  ]
+}

specs/3_product_development_s/system-ontology-framework/index.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Login Graph</title>
+
+  <script src="https://unpkg.com/cytoscape@3.26.0/dist/cytoscape.min.js"></script>
+
+  <style>
+    :root {
+      --bg: #f4efe7;
+      --panel: rgba(255, 255, 255, 0.88);
+      --ink: #14213d;
+      --muted: #5b6475;
+      --line: rgba(20, 33, 61, 0.12);
+      --ui: #2563eb;
+      --script: #0f766e;
+      --data: #a16207;
+      --returns: #7c3aed;
+      --navigates: #db2777;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      font-family: Georgia, "Times New Roman", serif;
+      color: var(--ink);
+      background:
+        radial-gradient(circle at top left, rgba(37, 99, 235, 0.14), transparent 28%),
+        radial-gradient(circle at top right, rgba(15, 118, 110, 0.14), transparent 26%),
+        linear-gradient(180deg, #f8f5ef 0%, var(--bg) 100%);
+    }
+
+    .page {
+      width: min(1400px, calc(100vw - 32px));
+      margin: 20px auto;
+      display: grid;
+      gap: 16px;
+    }
+
+    .hero {
+      display: grid;
+      gap: 10px;
+      padding: 20px 24px;
+      border: 1px solid var(--line);
+      border-radius: 20px;
+      background: var(--panel);
+      backdrop-filter: blur(10px);
+      box-shadow: 0 16px 42px rgba(20, 33, 61, 0.08);
+    }
+
+    .eyebrow {
+      margin: 0;
+      font-size: 12px;
+      font-weight: 700;
+      letter-spacing: 0.18em;
+      text-transform: uppercase;
+      color: var(--muted);
+    }
+
+    h1 {
+      margin: 0;
+      font-size: clamp(28px, 4vw, 44px);
+      line-height: 1;
+    }
+
+    .subtitle {
+      margin: 0;
+      max-width: 900px;
+      color: var(--muted);
+      font-size: 16px;
+      line-height: 1.5;
+    }
+
+    .legend {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 10px;
+      align-items: center;
+    }
+
+    .chip {
+      display: inline-flex;
+      align-items: center;
+      gap: 8px;
+      padding: 8px 12px;
+      border-radius: 999px;
+      border: 1px solid var(--line);
+      background: rgba(255, 255, 255, 0.72);
+      color: var(--ink);
+      font-size: 14px;
+      font-weight: 600;
+    }
+
+    .swatch {
+      width: 12px;
+      height: 12px;
+      border-radius: 999px;
+      background: currentColor;
+      box-shadow: inset 0 0 0 1px rgba(20, 33, 61, 0.15);
+    }
+
+    .graph-shell {
+      padding: 14px;
+      border: 1px solid var(--line);
+      border-radius: 24px;
+      background: rgba(255, 255, 255, 0.78);
+      box-shadow: 0 20px 48px rgba(20, 33, 61, 0.08);
+    }
+
+    #cy {
+      width: 100%;
+      height: 76vh;
+      min-height: 620px;
+      border-radius: 18px;
+      border: 1px solid rgba(20, 33, 61, 0.08);
+      background:
+        linear-gradient(rgba(20, 33, 61, 0.04) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(20, 33, 61, 0.04) 1px, transparent 1px),
+        linear-gradient(180deg, rgba(255, 255, 255, 0.98), rgba(248, 250, 252, 0.96));
+      background-size: 32px 32px, 32px 32px, auto;
+      overflow: hidden;
+    }
+
+    @media (max-width: 800px) {
+      .page {
+        width: min(100vw - 16px, 1400px);
+        margin: 8px auto 16px;
+      }
+
+      .hero,
+      .graph-shell {
+        padding: 14px;
+        border-radius: 18px;
+      }
+
+      #cy {
+        height: 72vh;
+        min-height: 520px;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main class="page">
+    <section class="hero">
+      <p class="eyebrow">System Graph</p>
+      <h1>Login Flow Map</h1>
+      <p class="subtitle">Cytoscape view of the login-side app graph, showing browser UI, scripts, datastores, and the relationships between them.</p>
+      <div class="legend" aria-label="Graph legend">
+        <span class="chip"><span class="swatch" style="color: var(--ui);"></span>UI node</span>
+        <span class="chip"><span class="swatch" style="color: var(--script);"></span>Script node</span>
+        <span class="chip"><span class="swatch" style="color: var(--data);"></span>Datastore node</span>
+        <span class="chip"><span class="swatch" style="color: var(--returns);"></span>Return edge</span>
+        <span class="chip"><span class="swatch" style="color: var(--navigates);"></span>Navigation edge</span>
+      </div>
+    </section>
+
+    <section class="graph-shell">
+      <div id="cy"></div>
+    </section>
+  </main>
+
+  <script src="app.js"></script>
+</body>
+</html>

specs/3_product_development_s/system-ontology-framework/system-ontology-framework.md

@@ -0,0 +1,175 @@
+# Overview
+A framework that defines a system ontology approach where a complex software system is modeled as a structured graph (nodes and relationships) that serves as the single source of truth—allowing AI to automatically generate diagrams, detect issues, simulate changes, and even build code. It’s important because it transforms system design from static documentation into a machine-readable, AI-operable model, enabling automation, consistency, and far more intelligent development and scaling of software systems.
+
+# C4 Model (industry standard)
+
+1. Context (system in the world)
+2. Container (apps/services)
+3. Component (modules inside apps)
+4. Code (classes/functions)
+
+## Tools
+
+### graphical interface (lucidchart)
+- start here to map the system
+- this is for high-level thinking, presentation, human UI
+
+### spreadsheet (System catalog / service registry / data dictionary hybrid)
+
+As you build the system and its files and components, you create a machine-readable system graph that is a declarative system model where everything is described, and everything else is derived from it:
+- diagrams
+- monitoring
+- orchestration
+- agents
+The spreadsheet is the SOURCE OF TRUTH. JSON is a derived artifact. The Cytoscape graph is a VIEW. Never manually edit JSON long-term — generate it.
+
+Ai can use this to:
+1. generate diagrams automatially
+2. detect issueso
+- orphaned components
+- circular dependencies
+- unused scripts
+- data inconsistencies
+3. build agents
+- “Find all nodes where operation=VALIDATE and auto-optimize”
+4. simulate system
+- what happens if ...
+- what breaks if ...
+5.generate code scaffolding
+- FastAPI routes
+- cron jobs
+- validators
+6. build inference layer
+See template. 
+
+### Process
+1. build graphical interface for human documenting components and flow. Build in small, disrete modules you can put a box around that is on its own.  Define flows, outcomes.  Then, define nodes and edges - ontology draft
+2. Code the components
+3. Have AI create the actual graph in the spreadsheet based on the templates - see in same folder for this file. Create in csv, copy and save as csv, open csv in spreadsheet, copy to gsheets file. Try to fit to validators sheet 
+4. Have AI build the corresponding json file. Invalid JSON (e.g. NaN) → graph will not render. See template of prior one created - graph_edges_nodes.json This is ontology final
+4. Create browser-based cytoscape graph viewer - instructions below
+5. Fix mismatches between ontologt draft and ontology final
+
+#### Example:
+
+Add Customer Module
+Trigger: user submits form
+Input: customer data
+Process:
+    validate → write → index update
+Output:
+    new customer JSON
+
+Graph:
+
+UI → API → validate → storage → index → response
+
+If a module does more than one of these → it’s too big.
+
+#### Practical Rules for Your Future Builds
+1. Rule 1 — Always start with flow
+
+Before coding:
+
+User action → API → validation → storage → response
+
+2. Rule 2 — Cap module size
+
+If a module:
+
+touches > 5 files
+has > 1 primary route
+
+👉 split it
+
+3. Rule 3 — Every module must be drawable as a box
+
+If you can’t draw a clean box around it:
+
+👉 it’s not a module yet
+
+4. Rule 4 — Graph is not documentation
+
+This is important:
+
+Your graph is not a diagram — it is a system constraint
+
+You should be able to say:
+
+“this edge is invalid”
+“this node should not exist”
+
+### System Graph
+
+1. Create project in WSL
+mkdir ~/(name)-system-graph
+cd ~/(name)-system-graph
+2. create index.html - adjust file name being rendered (step 4)
+3. create app.js - adjust file name being rendered (step 4)
+4. convert spreadsheet to JSON and create _(name)_graph_cytoscape.json
+- - JSON MUST be a flat array of Cytoscape elements:
+
+[
+  { data: { id, label } },
+  { data: { source, target } }
+]
+
+NOT:
+{ nodes: [...], edges: [...] }
+- - Node IDs must be:
+- - - exact string match
+-  - -trimmed (no trailing spaces)
+-  - - no annotations (remove "(API)", "(DB)", etc.)
+Edges must reference these exact IDs.
+5. copy to WSl folder  cp /mnt/c/Users/<your-user>/Desktop/lod_graph_cytoscape.json ~/system-graph/
+5. run on wsl: python3 -m http.server 8000
+6. http://localhost:8000
+7. Always edit the file the server is serving (WSL). Invalid JSON (e.g. NaN) → graph will not render. Node IDs must match edge references exactly. Use fetch debug to verify actual runtime data
+- - fetch('lod_graph_cytoscape.json')
+  .then(r => r.text())
+  .then(console.log)
+8. Edit and adjust scripts as needed using codex desktop or in terminal, then output the files to desktop to save cp ~/system-graph/app.js ~/system-graph/index.html ~/system-graph/lod_graph_cytoscape.json /mnt/c/Users/edsoe/Desktop/
+
+
+## Other
+
+### Add environment boundary rule (this was THE issue)
+
+You mention copying, but not the underlying principle.
+
+Add:
+
+The browser only sees files served by the WSL server.
+
+Editing files on Desktop has no effect until copied into WSL.
+
+Always verify the runtime file, not the edited file.
+
+### Add minimal test graph (for sanity check)
+
+This is a must-have reset tool:
+
+[
+  { "data": { "id": "A", "label": "A" } },
+  { "data": { "id": "B", "label": "B" } },
+  { "data": { "id": "e1", "source": "A", "target": "B" } }
+]
+
+Use when debugging pipeline.
+
+### Add layout note (optional but useful)
+Default layout: cose (force-directed)
+
+If graph looks flat or clustered:
+- adjust layout
+- or check connectivity
+
+### Common Failure Modes
+- | Symptom              | Cause                               |
+| -------------------- | ----------------------------------- |
+| Blank graph          | JSON invalid OR fetch failed        |
+| “Unexpected token N” | NaN in JSON                         |
+| A→B→C won’t change   | editing wrong file (WSL vs Desktop) |
+| Graph collapsed      | edge references missing nodes       |
+| No console logs      | app.js not loaded                   |
+

specs/3_product_development_s/system-ontology-framework/system-ontology-validators.csv

@@ -0,0 +1,28 @@
+module,sub-module,active,node-id,code-base,type,retry-policy-indempotent,logging,metrics,execution-environment,vm-environment,owner,from-node-to-node,edge-type,entity,execution,schedule,state-transition,dependencies,observability-hooks,criticality
+customer-db,login,prod,file:login.js,html,UI,yes,yes,,browser/client,lod-dev-app,system,file:login.js,calls,attachment file,user,1-minute,auth dependency loaded,file:login.js,logs,low
+,customers,dev,file:login.html,js,Script,no,no,,backend/vm,lod-prod-app,ingestion-agent,file:login.html,reads,attachment record,event,3-minutes,authenticated,file:login.html,metrics,medium
+,,ideation,login API,py,Datastore,,print-based,,infrastructure,,inference-agent,login API,writes,auth token,cron,5-minutes,authorized,login API,alerts,high
+,,archived,auth system,.env,Cron,,,,,,,auth system,triggers,chunk,manual,manual,chunked,auth system,,
+,,,environment config,browser DOM (in memory),Template,,,,,,,environment config,validates,credentials,,on change,config loaded,environment config,,
+,,,localStorage ,,API,,,,,,,localStorage ,transforms,customer index,,on load/reload,customer created/updated/deleted,localStorage ,,
+,,,file:dashboard.html,,Schema,,,,,,,file:dashboard.html,queues,customer json,,on login,customer loaded,file:dashboard.html,,
+,,,DOM (#msg),,External,,,,,,,DOM (#msg),depends_on,customer record,,on mutation,customer loaded/saved,DOM (#msg),,
+,,,file:auth.py,,Service,,,,,,,file:auth.py,returns,dog index,,on request,dog index built,file:auth.py,,
+,,,file:customer.py,,Config,,,,,,,file:customer.py,navigates,error message,,on submit,error,file:customer.py,,
+,,,file:customers_index.py,,,,,,,,,file:customers_index.py,imports,PID,,on upload,file persisted/json updated,file:customers_index.py,,
+,,,file:dogs.py,,,,,,,,,file:dogs.py,,session,,on upload,index built,file:dogs.py,,
+,,,file:upload.py,,,,,,,,,file:upload.py,,token,,on upload,index rebuild callable,file:upload.py,,
+,,,file:validators.py,,,,,,,,,file:validators.py,,user,,on upload,indexed,file:validators.py,,
+,,,file:main.py,,,,,,,,,file:main.py,,validation rules,,,inferred,file:main.py,,
+,,,file:requirements.txt,,,,,,,,,file:requirements.txt,,validator request,,,rules dependency loaded,file:requirements.txt,,
+,,,.venv,,,,,,,,,.venv,,,,,rules returned,.venv,,
+,,,_pycache_,,,,,,,,,_pycache_,,,,,storage dependency loaded,_pycache_,,
+,,,file:storage.py,,,,,,,,,file:storage.py,,,,,submitted,file:storage.py,,
+,,,file:validate.py,,,,,,,,,file:validate.py,,,,,validated,file:validate.py,,
+,,,file:validators_config.py,,,,,,,,,file:validators_config.py,,,,,validated,file:validators_config.py,,
+,,,file:add_customer.js,,,,,,,,,file:add_customer.js,,,,,validation dependency loaded,file:add_customer.js,,
+,,,file:app.js,,,,,,,,,file:app.js,,,,,,file:app.js,,
+,,,file:dogs.html,,,,,,,,,file:dogs.html,,,,,,file:dogs.html,,
+,,,file:dogs.js,,,,,,,,,file:dogs.js,,,,,,file:dogs.js,,
+,,,file:edit_customer.html,,,,,,,,,file:edit_customer.html,,,,,,file:edit_customer.html,,
+,,,file:validators-ui.js,,,,,,,,,file:validators-ui.js,,,,,,file:validators-ui.js,,

specs/3_product_development_s/system-ontology-framework/system_ontology - edges.csv

@@ -0,0 +1 @@
+module,active,edge-id,from-node,to-node,edge-type,entity,execution,schedule,state-transition,dependencies,criticality,execution-environment

specs/3_product_development_s/system-ontology-framework/system_ontology - nodes.csv

@@ -0,0 +1 @@
+module,sub-module,active,node-id,location,code-base,type,retry-policy,indempotent,logging,metrics,alerts,execution-environment,vm-environment,owner,external-connections,system-version,component-version,script-version

specs/4_finance_s/.gitkeep.md

@@ -0,0 +1 @@
+keep

specs/5_production-logistics_s/.gitkeep.md

@@ -0,0 +1 @@
+keep

specs/6_marketing_s/.gitkeep.md

@@ -0,0 +1 @@
+keep

specs/6_marketing_s/marketing_s.md

@@ -0,0 +1 @@
+A front-facing website builder and template is here:  "C:\projects\indx\indx-front-website"/https://projects.eddiesoehnel.com/adminprojects/indx-front-website   

specs/7_sales-distribution_s/.gitkeep.md

@@ -0,0 +1 @@
+keep

specs/8_support_s/.gitkeep.md

@@ -0,0 +1 @@
+keep

specs/agents.md

@@ -0,0 +1,55 @@
+
+# Context
+
+To understand the general process for this repo, please review the PRODUCT-DEV-OS.md file.  
+
+# This Document
+
+Functions more like a router, telling AI where to find stuff.
+
+# This Repo
+
+- Rules for editing code
+- AI should modify docs before modifying code. 
+- All new features must update data-model.md. All tests must pass before merge.
+
+# Where To Find Documentation
+
+in specs folder. Ignore anything with "draft" in the name.  Pointy out workflow docs, skill docs (or agent skills) and system documentation (describing different parts of the system)
+
+
+# Additional General Requirements
+
+ Code is created in files.  Code is well documented and explains why the code exists, what it does, maintenance tips, gotchas if any.
+ 
+ ## Change Propagation Rules
+ 
+ When any of the following are modified:
+ - API responses
+ - data structures
+ - business logic
+ - system behavior
+ 
+ You must:
+ 
+ 1. Identify all affected layers:
+    - specs
+    - srv
+    - data-ops
+    - tests
+ 
+ 2. Update only the impacted sections, but in audit mode first. Do not edit yet until I review and give command to proceed with updates
+ 
+ 3. Maintain consistency across:
+    - schema definitions
+    - example data
+    - architecture documentation
+ 
+ 4. Add an entry to `specs/decisions.md` if the change alters:
+    - system behavior
+    - data contracts
+    - architectural assumptions
+ 
+ 5. Do not rewrite entire documents unless explicitly instructed
+ 
+ Consider writing a change audit template md file for above. 

specs/decisions.md

@@ -0,0 +1 @@
+decision.md

specs/personas.md

@@ -0,0 +1,19 @@
+# Description
+
+As AI may run sub-agents, this document defines the personas for those sub-agents. Set up clear path where AI agents orchestrate other AI agents. This is where it is done. 
+
+# Sub-Agent Personas
+
+Each of these "owns" a portion of the docs, and reviews against their own documentation, including suggesting where their own docs need to be adapted.
+
+## Designer
+
+## Architect
+
+## Domain Expert
+
+## Code Expert
+
+## Performance Expert
+
+## Human Advocate

srv/digital/app/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/models/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/routes/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/scripts/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/services/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/ui/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/digital/utils/.gitkeep.md

@@ -0,0 +1 @@
+keep

srv/physical/.gitkeep.md

@@ -0,0 +1 @@
+keep

tasks-workflows/min-viable-product-build.md

@@ -0,0 +1,36 @@
+# What specifically must be true when this is done? Define in terms of metrics (revenue, costs, use metrics, etc), user flows, user delight, the feeling achieved when this outcome is realized, what it allows, where it can lead, how it leverages.  
+
+1. Homepage for nSIG.earth that resolves to nSIG.indx.earth.  
+- Describes the platform, why, how and what they get from it.  Keep it short, brief
+
+2. Signup page:
+- instreuctions to become a member, which is complete PID-template, save to google drive or onedrive, open persmissions for viewing, provide the URL and email and submit.  
+- T&C and disclaimer agreed to before submit
+- include your referral URL to signup.  
+
+3. ON sign-up
+- System takes the email and PID URL, creates a JSON file representing the user and their PID.  Stores this data in the JSON. Creates a referral URL as well unique to this person. 
+- System displays confirm page we got it.  Check your email. 
+- System sends them email confirming membership, the basic logic commands to interact with system, what to expect in terms of future emails and matching.  But we are alpha version, so be honest and tell people nbot matching for awhile.  We are building.  Forget about us, but white list the email from us.  Build your PID - improve it, think about it, etc.  Use this time to get it right for you.  Also include link inb email that confirms their email to our system.  Gives them a referral URL so they can tell others.  But, restircit it to 5 people each to start.
+- As admin, I can change that for each person.  My JSON may have more so I can send out to more people. 
+
+4. System Logic/Scripts
+- Referral URL restrictions - how many times can each one be reused?  To start, limit to 5. Coutner in the user JSON file that winds down when all 5 used.  
+- Optional to shut off all new submissions form system as a global rule, so we can stop getting new referrals.   
+
+What are the non-negotiables? (safety, cost, time, inputs)
+1. System adheres to system.md to be simple, fast, secure, basic, just works.  Nothing fancy or advanced.  
+
+Sequences, tasks, modules, dependencies, components
+ - na
+
+Vague input → mediocre AI output
+Precise constraints → high-quality execution
+ - what is vague about above that needs to be improved to provide clarity to AI to complete thie build-plan?
+
+Think in terms of outcomes - what you want to see when all is done.
+- A basic system as above that accepts submissions, nothing else.  No processing.  We want to start to build interest, get people to think about their PIDs. This 
+
+Break that outcome into components, dependencies, unknowns. You are converting the outcome, or problem, or rask or idea into machine-operable structure. 
+
+Turn messy reality of achieving outcomes into machine-readable objects, which are the documents and how they are structured throughout the Product Dev OS framework

tasks-workflows/task-build-plan-template.md

@@ -0,0 +1,14 @@
+What specifically must be true when this is done? Define in terms of metrics (revenue, costs, use metrics, etc), user flows, user delight, the feeling achieved when this outcome is realized, what it allows, where it can lead, how it leverages.  
+
+What are the non-negotiables? (safety, cost, time, inputs)
+
+Sequences, tasks, modules, dependencies, components
+
+Vague input → mediocre AI output
+Precise constraints → high-quality execution
+
+Think in terms of outcomes - what you want to see when all is done.
+
+Break that outcome into components, dependencies, unknowns. You are converting the outcome, or problem, or rask or idea into machine-operable structure. 
+
+Turn messy reality of achieving outcomes into machine-readable objects, which are the documents and how they are structured throughout the Product Dev OS framework

tests/.gitkeep.md

@@ -0,0 +1 @@
+keep