GitZeq — Framework-Verified Decentralized Git

GitZeq is the Zeq OS self-hosted Git platform. It is built on Gitea, a lightweight Git forge, extended with the Zeq OS mathematical framework so that every repository, commit, and branch can be cryptographically verified by 1,576 operators pulsing at 1.287 Hz with a 0.1% precision guarantee.

Access GitZeq: http://localhost/git/

---

Getting Started

Creating an Account

GitZeq uses Equation Auth — the same zero-PII identity system used across all Zeq OS applications. No email address or password is required.

1. Navigate to GitZeq
2. Click Sign In with Equation on the login page
3. Enter your mathematical equation (e.g. E = mc^2 + h*f) and a display name
4. Your equation is hashed into a unique ZID (e.g. zeq-735e3e366813) — this is your identity everywhere in Zeq OS
5. You are now signed in across all Zeq OS apps

Your equation is shown once during registration. Copy it somewhere safe — it cannot be recovered. The same equation always produces the same ZID, so you can log in from any device.

Creating a Repository

1. Click the + icon in the top navbar, or go to New Repository
2. Enter a repository name and optional description
3. Choose visibility: Public (anyone can view) or Private (only you and collaborators)
4. Optionally initialize with a README, .gitignore template, or license
5. Click Create Repository

Cloning a Repository

# HTTPS
git clone http://localhost/git/your-username/your-repo.git

# SSH (if configured)
git clone git@localhost:your-username/your-repo.git

Pushing Code

cd your-project
git init
git remote add origin http://localhost/git/your-username/your-repo.git
git add -A
git commit -m "Initial commit"
git push -u origin main

---

Core Git Features

GitZeq supports all standard Git forge operations:

Repositories

• Branches — create, protect, compare, and merge branches
• Tags & Releases — semantic versioning with downloadable archives
• Forks — fork any public repository into your account
• Mirroring — mirror repositories from GitHub, GitLab, or any remote

Issues & Project Management

• Issues — create, assign, label, and track bugs and feature requests
• Labels & Milestones — organize work into releases and categories
• Project Boards — Kanban-style boards for tracking progress
• Assignees — assign issues and PRs to team members

Pull Requests

• Code Review — inline comments, review approvals, and change requests
• Merge Strategies — merge commit, rebase, squash, or fast-forward
• Branch Protection — require reviews, status checks, and signed commits before merging
• Auto-merge — automatically merge when all checks pass

Organizations & Teams

• Organizations — group repositories under a shared namespace (e.g. zeq-os)
• Teams — create teams with granular permissions (read, write, admin) per repository
• Member Management — invite collaborators by ZID

Webhooks & Integrations

• Webhooks — HTTP callbacks on push, PR, issue, and release events
• API — full REST API for automation (see API Browser)

---

Framework Verification

This is what makes GitZeq unique. Every piece of content — repositories, commits, files, issues — can be mathematically verified through the Zeq OS framework.

How It Works

1. Submit — any content is submitted for verification via the /api/verify/check endpoint
2. Compute — the framework runs the content through a selection of kinematic operators, computing a master sum, KO42 metric tensor value, and phase alignment
3. Precision Check — the computed sum is compared against the framework's master equation sum; if the deviation is within 0.1%, verification passes
4. Badge — a traffic-light badge is assigned (see below)

Decentralized Challenge Network

Any verification can be challenged by other nodes on the mesh sync pulse network. A challenger re-runs the computation with a different selection of operators to see if the 0.1% precision holds. This creates a consensus-based truth mechanism for computational integrity.

Node A submits verification → uses operators [KO42_7, HRO00, PSI96]
Node B challenges           → uses operators [GR33, NM21, QM1, QM2, KO42_7]
Node C challenges           → uses operators [MK1, QL1, PSI96, GR33]

If all nodes agree within 0.1% → consensus = verified (green badge)
If disagreement detected      → consensus = disputed (red badge)

Consensus scoring:

• 2+ challenges with 66%+ agreement → verified (green)
• 2+ challenges with less than 33% agreement → disputed (red)
• Partial verification → yellow badge

Traffic-Light Badge System

Every verified piece of content gets a badge:

Badge	Meaning	Requirements
Green	Fully verified	3+ operators used, precision within 0.1%, KO42 metric tensor applied, 66%+ consensus from 2+ challenges
Yellow	Partially verified	Some operators applied or mid-range consensus (33-66%)
Red	Unverified / Disputed	No verification performed, or consensus below 33%

Verification API

Submit for Verification

curl -X POST http://localhost/api/verify/check \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "repository",
    "content_id": "zeq-os/my-repo",
    "query": "verify repository integrity",
    "operators": ["KO42_7", "HRO00", "PSI96", "MK1", "QL1"]
  }'

Response:

{
  "id": "a1b2c3d4-...",
  "badge": "green",
  "status": "verified",
  "operators": ["KO42_7", "HRO00", "PSI96", "MK1", "QL1"],
  "operator_count": 5,
  "master_sum": 1546.287,
  "precision_deviation": 0.00042,
  "precision_within_target": true,
  "ko42_value": 42.0,
  "domains": ["KO42", "HRO", "PSI", "MK", "QL"],
  "zeqond": 2105483,
  "phase": 0.777
}

Challenge a Verification

curl -X POST http://localhost/api/verify/challenge \
  -H "Content-Type: application/json" \
  -H "X-Node-Id: my-node-01" \
  -d '{
    "verification_id": "a1b2c3d4-...",
    "operators": ["GR33", "NM21", "QM1", "QM2", "KO42_7"]
  }'

Response includes consensus:

{
  "challenge_id": "e5f6g7h8-...",
  "result": "agree",
  "within_tolerance": true,
  "consensus": {
    "score": 1.0,
    "challenges": 2,
    "agrees": 2,
    "status": "verified"
  },
  "badge": "green"
}

Check Verification Status

curl "http://localhost/api/verify/status?content_type=repository&content_id=zeq-os/my-repo"

Live Verification Events

Subscribe to real-time verification events via WebSocket:

const ws = new WebSocket('ws://localhost:8080/ws/verify');
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // data.type: 'verification_created' or 'challenge_result'
  console.log(data.channel, data.type, data);
};

---

Equation Auth on GitZeq

GitZeq integrates with the Zeq OS equation auth system. When you sign in with your equation via the zeq-nav bar, your session is recognized across GitZeq automatically:

• Sign In/Register buttons are hidden when you are equation-authenticated
• Your display name appears in the GitZeq navbar with a live pulse indicator
• Login page shows a "Login with Equation" card above the native form
• All API calls accept the zeq-auth Bearer token (Authorization: Bearer {base64url-token})

If you need a native GitZeq account (for SSH keys or Gitea-specific features), you can still create one via the native form below the equation login card.

---

Repository Best Practices

Branch Strategy

main              ← production-ready code (protected)
  └── develop     ← integration branch
       ├── feature/new-operator   ← feature branches
       └── fix/precision-bug      ← bugfix branches

Commit Messages

Use clear, descriptive commit messages:

feat: add quantum entanglement operator QE42
fix: correct precision deviation in KO42 tensor calculation
docs: update verification API examples

Branch Protection

For important repositories, enable branch protection on main:

1. Go to Settings > Branches
2. Add a protection rule for main
3. Enable: Require pull request reviews, Require status checks to pass
4. This ensures all changes go through review and verification

---

Organizations

The zeq-os organization contains all official Zeq OS repositories. To create your own organization:

1. Click + > New Organization in the top navbar
2. Choose a name and visibility
3. Create Teams with appropriate permissions (Owners, Developers, Readers)
4. Add repositories to the organization

---

Administration

Gitea Admin Panel

If your ZID is listed in the ZEQ_ADMIN_ZIDS environment variable, you have admin access. The Gitea admin panel is available at /git/-/admin for managing:

• Users and organizations
• Repository settings
• System configuration
• Application tokens and OAuth2

API Tokens

Generate personal access tokens for API automation:

1. Go to Settings > Applications
2. Enter a token name and select scopes
3. Click Generate Token — copy it immediately (shown only once)

# Use the token for API calls
curl -H "Authorization: token YOUR_TOKEN" http://localhost/git/api/v1/repos/search

Gitea REST API

The full Gitea API is available at http://localhost/git/api/v1/. Browse it interactively at the API Browser.

Common endpoints:

Endpoint	Description
GET /api/v1/repos/search	Search repositories
POST /api/v1/user/repos	Create a repository
GET /api/v1/repos/{owner}/{repo}	Get repository details
GET /api/v1/repos/{owner}/{repo}/commits	List commits
POST /api/v1/repos/{owner}/{repo}/issues	Create an issue
GET /api/v1/orgs	List organizations

---

SSH Configuration

To use SSH for Git operations:

1. Generate an SSH key if you don't have one:

   ssh-keygen -t ed25519 -C "your-zid"

2. Copy the public key:

   cat ~/.ssh/id_ed25519.pub

3. Go to Settings > SSH / GPG Keys > Add Key
4. Paste the public key and save
5. Test the connection:

   ssh -T git@localhost -p 22

---

Troubleshooting

"Authentication required" on push

Make sure you are logged in. For HTTPS pushes, GitZeq will prompt for credentials. Use your GitZeq username and a personal access token as the password.

Repository not showing Framework Verified badge

The badge appears automatically on all repository pages via the GitZeq widget. If missing, try a hard refresh (Cmd+Shift+R / Ctrl+Shift+R).

Verification returning "red" badge

This means the content has not been submitted for verification yet. Use the /api/verify/check endpoint to submit it, or wait for automatic verification via the mesh sync pulse.

Theme not loading

GitZeq's dark theme is injected via the zeq-gitea.js widget. If you see the default Gitea light theme, check that nginx is serving the widget files correctly:

curl -I http://localhost/widget/zeq-gitea.js
# Should return 200 OK