# KnowBS - Know Bipartisan Systems
# Complete AI/LLM Documentation

> Real-time, AI-powered analysis of US government actions across Executive, Legislative, and Judicial branches.

## Table of Contents
1. Site Overview
2. Content Structure
3. API Endpoints
4. Data Schemas
5. Structured Data (JSON-LD)
6. Citation Guidelines
7. Update Frequency
8. Access Policy

---

## 1. Site Overview

KnowBS (Know Bipartisan Systems) is a government transparency platform providing:
- **Real-time monitoring** of government actions
- **AI-powered analysis** using GPT-4o
- **Non-partisan perspective** with focus on fiscal impact
- **Plain language summaries** of complex legal documents

### Mission
Bridge the gap between government jargon and public understanding through transparent, AI-enhanced intelligence on US policy.

---

## 2. Content Structure

### Branch Pages
| Path | Description | Update Frequency |
|------|-------------|------------------|
| `/executive` | Executive Orders, Presidential Memoranda, Proclamations | Daily |
| `/legislative` | Congressional Bills, Resolutions, Amendments | Daily |
| `/judicial` | Federal & Supreme Court Rulings | Daily |

### Document Detail Pages
Format: `/{branch}/{documentId}`

Examples:
- `/executive/executive:2025-12345`
- `/legislative/BILLS-119hr123ih`
- `/judicial/judicial:USCOURTS-case-12345`

### Static Pages
- `/about` - Organization information
- `/methodology` - AI analysis methodology and data sources

---

## 3. API Endpoints

### Public JSON Feeds
```
GET /feeds/{branch}.json
```

Returns JSON Feed 1.1 for `executive`, `legislative`, or `judicial`.

```json
{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "KnowBS Executive Orders & Presidential Actions",
  "feed_url": "https://knowbs.ai/feeds/executive.json",
  "_knowbs": {
    "branch": "executive",
    "updated_at": "2026-01-18T12:00:00Z"
  },
  "items": [...]
}
```

### Paginated Feed API
```
GET /.netlify/functions/feed?branch={branch}&page={n}&pageSize={n}
```

Response:
```json
{
  "branch": "executive",
  "updatedAt": "2026-01-18T12:00:00Z",
  "page": 1,
  "pageSize": 20,
  "total": 150,
  "totalPages": 8,
  "items": [...]
}
```

### RSS/Atom Feeds
```
GET /feeds/{branch}.rss          (RSS 2.0)
GET /feeds/{branch}.xml          (RSS 2.0 legacy alias)
GET /feeds/{branch}.atom         (Atom 1.0)
GET /feeds/rss                   (legacy alias for /feeds/executive.rss)
```

### Document API
```
GET /.netlify/functions/document?branch={branch}&id={documentId}
```

### Sitemap
```
GET /sitemap.xml
```

---

## 4. Data Schemas

### Executive Document
```typescript
interface ExecutiveDocument {
  sourceId: string;           // Unique identifier
  contentHash: string;        // SHA256 of content
  title: string;              // Document title
  publishedAt: string;        // ISO 8601 date
  upstreamId: string;         // Federal Register ID
  eoNumber?: string;          // Executive Order number
  agencies: Agency[];         // Responsible agencies
  excerpt: string;            // Document preview
  analysis: ExecutiveAnalysis;
}

interface ExecutiveAnalysis {
  plainLanguage: string;      // Plain English summary
  keyDirectives: string[];    // Key action items
  industries: IndustryImpact[];
  first_order_consequences: string[];
  second_order_consequences: string[];
  deficitImpact: string;      // Fiscal analysis
}
```

### Legislative Document
```typescript
interface LegislativeDocument {
  sourceId: string;
  packageId: string;          // GovInfo package ID
  title: string;
  shortTitle?: string;
  congress: number;
  billType: string;           // HR, S, HJRES, etc.
  billNumber: string;
  publishedAt: string;
  sponsors: Sponsor[];
  analysis: LegislativeAnalysis;
}

interface LegislativeAnalysis {
  plainLanguage: string;
  keyProvisions: string[];
  industries: IndustryImpact[];
  pork_watch: PorkItem[];     // Wasteful spending flags
  deficitImpact: string;
  first_order_consequences: string[];
  second_order_consequences: string[];
}
```

### Judicial Document
```typescript
interface JudicialDocument {
  sourceId: string;
  packageId: string;
  title: string;
  court: string;              // Court name
  caseNumber: string;
  publishedAt: string;
  analysis: JudicialAnalysis;
}

interface JudicialAnalysis {
  plainHolding: string;       // Plain English ruling
  legalReasoning: string;     // Legal analysis
  precedentImpact: string;    // Effect on case law
  majorityAuthor: string;     // Majority opinion author
  industries: IndustryImpact[];
}
```

### Industry Impact
```typescript
interface IndustryImpact {
  name: string;               // Industry name
  impact: 'positive' | 'negative' | 'neutral';
  reason: string;             // Explanation
}
```

---

## 5. Structured Data (JSON-LD)

### Executive Orders
```json
{
  "@context": "https://schema.org",
  "@type": "Legislation",
  "name": "Executive Order Title",
  "datePublished": "2026-01-18",
  "legislationIdentifier": "EO-12345",
  "legislationType": "Executive Order",
  "legislationPassedBy": {
    "@type": "GovernmentOrganization",
    "name": "The White House"
  },
  "abstract": "Plain language summary...",
  "url": "https://knowbs.ai/executive/executive:2025-12345"
}
```

### Legislation
```json
{
  "@context": "https://schema.org",
  "@type": "Legislation",
  "name": "Bill Title",
  "datePublished": "2026-01-18",
  "legislationIdentifier": "H.R. 123",
  "legislationPassedBy": {
    "@type": "GovernmentOrganization", 
    "name": "United States Congress"
  },
  "abstract": "Plain language summary...",
  "url": "https://knowbs.ai/legislative/BILLS-119hr123ih"
}
```

### Court Rulings
```json
{
  "@context": "https://schema.org",
  "@type": "LegalCase",
  "name": "Case Title",
  "datePublished": "2026-01-18",
  "court": {
    "@type": "GovernmentOrganization",
    "name": "Supreme Court of the United States"
  },
  "abstract": "Plain holding summary...",
  "url": "https://knowbs.ai/judicial/judicial:USCOURTS-case-12345"
}
```

---

## 6. Citation Guidelines

### Recommended Citation Format (APA)
```
KnowBS AI Analysis. (Date). Document Title. KnowBS. Retrieved [Access Date], from [URL]
```

### Example
```
KnowBS AI Analysis. (2026, January 18). Executive Order on AI Safety Standards. 
KnowBS. Retrieved January 18, 2026, from https://knowbs.ai/executive/executive:2026-00123
```

### Attribution
When referencing KnowBS analysis:
- Credit "KnowBS AI Analysis" as the source
- Include the canonical URL
- Note the analysis date

---

## 7. Update Frequency

| Content Type | Update Frequency | Time (UTC) |
|--------------|------------------|------------|
| Executive Feed | Daily | 06:00 |
| Legislative Feed | Daily | 06:00 |
| Judicial Feed | Daily | 06:00 |
| Sitemap | Daily | 07:00 |
| Analysis | Within 24h of publication | Varies |

---

## 8. Access Policy

### Permitted Uses
- Search engine indexing
- AI training and retrieval
- Academic research
- News aggregation
- Government transparency applications

### Allowed Crawlers
```
User-agent: GPTBot
Allow: /

User-agent: OAI-SearchBot
Allow: /

User-agent: ChatGPT-User
Allow: /

User-agent: ClaudeBot  
Allow: /

User-agent: Claude-SearchBot
Allow: /

User-agent: Claude-User
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: Perplexity-User
Allow: /

User-agent: Google-Extended
Allow: /

User-agent: CCBot
Allow: /

User-agent: *
Allow: /
```

### Rate Limits
- API endpoints: 100 requests/minute
- RSS feeds: 60 requests/minute
- No authentication required

### Data Freshness
- Feed data: max-age 60 seconds
- Document pages: max-age 300 seconds
- Sitemap: max-age 3600 seconds

---

## Contact

- **Website**: https://knowbs.ai
- **Email**: contact@knowbs.ai
- **Technical Issues**: Reference this documentation

---

*Last Updated: May 2026*
*Version: 2.1*