diff --git a/Gemfile b/Gemfile
index 1198e742f..c5ba9b467 100644
--- a/Gemfile
+++ b/Gemfile
@@ -1,3 +1,3 @@
 source 'https://rubygems.org'
 
-gem 'ruby-protocol-buffers'
+gem 'ruby-protocol-buffers', '1.2.2'
diff --git a/Gemfile.lock b/Gemfile.lock
index c368bdb9d..5151acc4d 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -7,4 +7,4 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  ruby-protocol-buffers
+  ruby-protocol-buffers (= 1.2.2)
diff --git a/build_rprotoc b/build_rprotoc
index cdc6c853e..e019cc519 100755
--- a/build_rprotoc
+++ b/build_rprotoc
@@ -16,4 +16,5 @@ set -e
 echo "building ruby protocol buffers"
 bin/ruby-protoc $PROTO_FILES --proto_path $SRC --ruby_out $RUBY_OUT
 
+./package_ruby
 
diff --git a/package_ruby b/package_ruby
new file mode 100755
index 000000000..5e39d1064
--- /dev/null
+++ b/package_ruby
@@ -0,0 +1,51 @@
+#!/bin/bash
+
+echo "packaging ruby protocol buffers"
+pushd target/ruby > /dev/null
+
+rm -rf jampb
+
+bundle gem jampb > /dev/null
+
+# copy over built ruby code
+cp src/*.rb jampb/lib/jampb
+
+pushd jampb > /dev/null
+
+# define gemspec
+cat >> jampb.gemspec << EOF
+ 
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/jampb/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Seth Call"]
+  gem.email         = ["seth@jamkazam.com"]
+  gem.description   = %q{protocol buffers for jamkazam}
+  gem.summary       = %q{protocol buffers for jamkazam.}
+  gem.homepage      = "http://www.jamkazam.com"
+
+  gem.files         = ['Gemfile', 'Rakefile', 'README.md', 'jampb.gemspec', 'lib/jampb.rb', 'lib/jampb/client_container.pb.rb', 'lib/jampb/version.rb' ]
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "jampb"
+  gem.require_paths = ["lib"]
+  gem.version       = Jampb::VERSION
+end
+EOF
+
+# make sure library manifest includes the generated ruby file
+cat >> lib/jampb.rb << EOF
+require "jampb/version"
+require "jampb/client_container.pb"
+
+module Jampb
+end
+
+EOF
+
+gem build jampb.gemspec > /dev/null
+
+popd > /dev/null
+popd > /dev/null
+
diff --git a/src/client_container.proto b/src/client_container.proto
index 7a721325d..e4a3e0375 100644
--- a/src/client_container.proto
+++ b/src/client_container.proto
@@ -1,24 +1,105 @@
 
+// adding a new message:
+// within ClientMessage block, 
+//     create a new field in the enum Type section (100s are meant to be normal messages; 1000s are meant to be errors).  It will have new field number X
+//     create a optional message of the same name, and use the same field number X.
+// then at bottom of the file (or wherever; just outside any existing blocks), add your message definition.
+
 package jampb;
 
 message ClientMessage {
-    enum Type { LOGIN = 1; JOIN_JAM_SESSION = 2;}
+    enum Type { 
+        LOGIN = 100; 
+        LOGIN_ACK = 101; 
+        LOGIN_JAM_SESSION = 102; 
+        LOGIN_JAM_SESSION_ACK = 103;
+        USER_JOINED_JAM_SESSION = 104;
+        LEAVE_JAM_SESSION = 105;
+        LEAVE_JAM_SESSION_ACK = 106;
+
+        SERVER_GENERIC_ERROR = 1000;
+        }
 
     // Identifies which inner message is filled in
     required Type type = 1;
     required string target = 2;
     
     // One of the following messages can be populated
-    optional Login login = 100;
-    optional JoinJamSession join_jam_session = 101;
-}
-
-message JoinJamSession {
-  optional string user_token = 1; // token provided from previous login
-  optional string jam_session_id = 2; // id for jam_session
+    // Client-Server messages (to/from)
+    optional Login login = 100; // to server
+    optional LoginAck login_ack = 101; // from server
+    optional LoginJamSession login_jam_session = 102; // to server
+    optional LoginJamSessionAck login_jam_session_ack = 103; // from server 
+    optional UserJoinedJamSession user_joined_jam_session = 104; // from server to all members
+    optional LeaveJamSession leave_jam_session = 105;
+    optional LeaveJamSessionAck leave_jam_session_ack = 106;
+
+    // Client-Session messages (to/from)
+     
+
+    // Server-to-Client errors
+    optional ServerGenericError server_generic_error = 1000;
 }
 
+// target: server
+// sent from client to server to associate the connection with a user
+// either supply a username/password, or just supply token
+// if successful, a LoginAck is sent.
+// if errored, a GenericServerError is sent and the connection is closed.
 message Login {
-  optional string username = 1; // username
-  optional string token = 2; // a token provided by the server that validates this user
+    optional string username = 1; // username... could be email.  need to wait for prod requirements
+    optional string password = 2; // a password
+    optional string token = 3; // a token/cookie from previous successful login attempt or from 'token' field in .jam file
+}
+
+// target: client
+// sent from server to client to let the client know the login was successful,
+// and to also show the IP address of the client as seen by the server.
+message LoginAck {
+    optional string public_ip = 1;
+}
+
+// target: server
+// send from client to server to log in to a jam session and be 'present'.
+// if successful, a LoginJamSessionAck is sent with error = false, and Client-Session messages will be passed 
+// directly from client to all other client. Also, the server will generate a 'UserJoinedJamSession' message
+// and send it to all other users to let the others know the user is here.
+// if errored, a LoginJamSessionAck is sent with error = true.
+message LoginJamSession {
+   optional string jam_session = 1; 
+}
+
+// target: client
+// error = true if the LoginJamSession command failed.
+message LoginJamSessionAck {
+    optional bool error = 1;
+    optional string error_reason = 2;
+}
+
+// target: server
+// send from client to server to leave a previously joined jam session
+message LeaveJamSession {
+    optional string jam_session = 1;
+}
+
+// target: client
+// error = true if the session didn't exist, but otherwise this is intended to always work barring server unrecoverable errors
+message LeaveJamSessionAck {
+    optional bool error = 1;
+    optional string error_reason = 2;
+}
+
+// target: session:
+// sent by server to let the rest of the participants know a user has joined. 
+// this feels a little off; client could do this?  *shrug* can change.
+message UserJoinedJamSession {
+    optional string user_id = 1; // this is the user_id and can be used for user unicast messages
+    optional string username = 2; // meant to be a display name
+}
+
+// target: client
+// if you receive this, your connection will close after.
+// but gives the client a chance to know why.
+message ServerGenericError {
+    optional string error_msg = 1;
 }